| name | Documentation Standards |
| description | Essential rules for code comments, READMEs, and technical documentation. |
| metadata | {"labels":["documentation","comments","docstrings","readme"],"triggers":{"keywords":["comment","docstring","readme","documentation"]}} |
Documentation Standards - High-Density Standards
Essential rules for code comments, READMEs, and technical documentation.
Priority: P2 (MAINTENANCE)
Essential rules for maintaining proper code comments, READMEs, and technical documentation.
📝 Code Comments (Inline Docs)
- "Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
- Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
- Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
- TODOs: Use
TODO(username): description or FIXME to track technical debt with ownership.
- Workarounds: Document hacks and removal conditions (e.g., backend bug, version target).
- Performance Notes: Explain trade-offs only when performance-driven changes are made.
📖 README Essentials
- Mission: Clear one-sentence summary of the project purpose.
- Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
- Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
- : Documentation is part of the feature; keep it synchronized with code changes.
