tomevault-io Documentation Standards
Purpose: Defines the non-negotiable standards for code comments, docstrings, and global artifacts.
1. Red Flags (Anti-Rationalization)
STOP if you are thinking:
- "I'll add comments later" -> WRONG. Undocumented code is technical debt from the moment it is written.
- "The code is self-documenting" -> WRONG. Code explains how; comments explain why.
- "Artifacts are optional, I can skip them entirely" -> WRONG. Artifacts are part of delivery quality;
.AGENTS.mdmust follow project memory policy.
2. Docstrings & JSDoc
All classes and functions MUST have documentation.
Python
Use Google-style docstrings.
[!TIP] See
assets/templates/python_docstring.pyfor the format.
JavaScript / TypeScript
Use JSDoc standards.
[!TIP] See
assets/templates/jsdoc_template.tsfor the format.
3. Comments
- Why vs What: Explain the reason for logic, not the syntax.
- Work Tracking: Use
# T O D O:(Python) or// T O D O:(JS/TS) for future work.
4. Path Standards (CRITICAL)
- Relative Paths Only: When linking to internal files in Artifacts (PLAN.md, TASK.md), ALWAYS use relative paths.
- ✅
[Ref](src/main.py) - ✅
[.agent/skills/core.md](.agent/skills/core.md) - ❌
file:///Users/username/project/src/main.py - ❌
/Absolute/System/Path
- ✅
5. Artifacts (.AGENTS.md)
Policy: keep .AGENTS.md for source-code directories under memory tracking. Missing file should not fail execution; bootstrap when needed.
[!TIP] Use the template at
assets/templates/agents_md_template.md.
Rationalization Table
| Agent Excuse | Reality / Counter-Argument |
|---|---|
| "It's a throwaway script" | Scripts evolve into products. Documenting later costs 3x more time. |
| "I don't know the types yet" | Use Any or unknown but document what the value represents. |
6. Resources
assets/templates/: Collections of templates.examples/good_documentation.py: Gold standard example.
Source: MatrixFounder/Agentic-development — distributed by TomeVault.