7.5 KiB
Project Thoth Coding Standards
Version: 1.0
Status: Canonical Development Standard
Purpose
This document defines the engineering standards used throughout Project Thoth.
The objective is not merely to produce working software, but to produce software that remains understandable, maintainable, and portable over time.
These standards apply equally to:
- Human developers
- AI-assisted development
- Autonomous development agents
When implementation choices conflict with these standards, architectural decisions (ADRs) take precedence.
Core Principles
1. Architecture Before Code
Every significant implementation should begin with architecture.
If a design decision is expected to persist beyond a single implementation, document it in an Architecture Decision Record (ADR) before coding.
Code should implement architecture—not define it.
2. Prefer Refactoring Over Patching
When repeated fixes indicate a flawed design, refactor rather than accumulate patches.
Signs that refactoring is warranted include:
- duplicate logic
- increasing conditional complexity
- repeated bug fixes in the same area
- unclear module responsibilities
- growing technical debt
The goal is long-term simplicity, not short-term completion.
3. Single Responsibility
Every module should have one clear responsibility.
Examples:
Good:
- Conversation Discovery
- HTML-to-Markdown Conversion
- Markdown Serialization
- Metadata Generation
Poor:
- ExtractConversationAndGenerateMarkdownAndDownload()
If a component's name requires multiple conjunctions ("and", "or"), it likely has more than one responsibility.
4. Separation of Concerns
Capture, transformation, processing, and presentation are independent concerns.
Each should exist in its own layer.
No layer should assume the responsibilities of another.
5. Deterministic Behavior
Given the same input, Project Thoth components should produce the same output.
Randomness, hidden state, and side effects should be avoided unless explicitly required.
Repository Organization
The repository should separate concerns by purpose rather than technology.
Typical structure:
.thoth/
applications/
archive/
codex/
docs/
processors/
specifications/
Each top-level directory should represent a distinct architectural concern.
Module Design
Modules should be:
- cohesive
- loosely coupled
- independently testable
Modules should expose small, well-defined interfaces.
Avoid exposing internal implementation details.
Function Design
Functions should:
- perform one task
- have descriptive names
- avoid unnecessary side effects
- return predictable results
Prefer composition over deeply nested logic.
Error Handling
Errors should be:
- explicit
- actionable
- recoverable when practical
Never silently discard data.
When partial processing is possible:
- preserve available information
- report the failure
- continue processing where safe
Preservation takes precedence over perfection.
Logging
Logs should assist debugging without becoming part of the application's behavior.
Log messages should answer:
- What happened?
- Why did it happen?
- What should the developer investigate next?
Avoid excessive or repetitive logging.
Documentation
Document architecture rather than implementation details.
Prefer:
- ADRs
- specifications
- interfaces
- module responsibilities
Avoid comments that merely repeat what the code already expresses.
Comments should explain why, not what.
Naming
Choose names that reflect business concepts rather than implementation details.
Prefer:
- ConversationTurn
- CaptureConnector
- ManifestGenerator
Avoid:
- TempData
- Helper
- Utils
- Stuff
Names should communicate intent.
Interfaces
Define interfaces at architectural boundaries.
Examples include:
- Capture Connector
- Processor
- Serializer
Interfaces should remain stable even when implementations change.
Dependencies
Minimize external dependencies.
Before adding a dependency, ask:
- Does the standard library already solve this?
- Does this dependency simplify architecture?
- Is it actively maintained?
- Can the dependency be removed later without significant effort?
Favor long-lived, well-supported libraries.
File Formats
Project Thoth prefers open formats.
Preferred formats include:
- Markdown
- YAML
- JSON
- Plain text
Avoid introducing proprietary formats unless there is a compelling architectural reason.
Testing
Testing should occur at multiple levels.
Examples:
- Unit tests
- Integration tests
- End-to-end workflow tests
Where practical, preserve representative fixtures for regression testing.
Regression tests are especially important for parsers and capture connectors.
AI-Assisted Development
AI is a development assistant, not an architectural authority.
AI-generated code should be reviewed for:
- correctness
- simplicity
- architectural alignment
- maintainability
AI should implement established architecture rather than invent new architecture during implementation.
Work Orders
Implementation work should be described using Work Orders.
A Work Order should include:
- context
- objective
- constraints
- deliverables
- acceptance criteria
- architectural references
Work Orders should be executable with minimal additional explanation.
Refactoring
Refactoring should preserve observable behavior while improving internal structure.
Typical reasons include:
- simplifying design
- improving readability
- reducing duplication
- improving testability
- aligning implementation with updated architecture
Refactoring should not introduce unrelated feature work.
Code Reviews
Reviews should evaluate:
- Architectural alignment
- Correctness
- Readability
- Maintainability
- Simplicity
The primary question is not:
"Does it work?"
Instead ask:
"Will another developer understand this in two years?"
Performance
Optimize for clarity first.
Optimize for performance when:
- measurement identifies a bottleneck
- scalability requires it
- architectural goals demand it
Avoid premature optimization.
Security
Treat external input as untrusted.
Validate:
- user input
- downloaded content
- file paths
- URLs
- serialized data
Avoid embedding secrets in source code or repositories.
Backward Compatibility
When changing canonical formats:
- preserve compatibility where practical
- document breaking changes
- update specifications
- record architectural decisions in ADRs
Technical Debt
Technical debt should be visible.
Known debt should be documented rather than ignored.
Temporary solutions should include:
- rationale
- limitations
- expected future resolution
Definition of Done
Work is considered complete when:
- implementation satisfies the Work Order
- acceptance criteria are met
- architecture remains consistent
- documentation is updated if required
- tests pass (where applicable)
- no known regressions have been introduced
Completion is measured by quality, not by the number of lines of code written.
Coding Philosophy
Project Thoth values software that is:
- understandable
- deterministic
- modular
- portable
- maintainable
- testable
The objective is to create software that remains useful long after the original implementation has evolved.
Final Principle
Good software preserves knowledge.
Great software preserves understanding.
Every design decision, module, and line of code should make the project easier for the next developer—or the next AI assistant—to understand.