32 lines
905 B
Markdown
32 lines
905 B
Markdown
---
|
|
trigger: always_on
|
|
---
|
|
|
|
## Documentation Principles
|
|
|
|
### Self-Documenting Code
|
|
|
|
**Clear naming reduces need for comments:**
|
|
|
|
- Code shows WHAT is happening
|
|
- Comments explain WHY it's done this way
|
|
|
|
**When to comment:**
|
|
|
|
- Complex business logic deserves explanation
|
|
- Non-obvious algorithms (explain approach)
|
|
- Workarounds for bugs (link to issue tracker)
|
|
- Performance optimizations (explain trade-offs)
|
|
|
|
### Documentation Levels
|
|
|
|
1. **Inline comments:** Explain WHY for complex code
|
|
2. **Function/method docs:** API contract (parameters, returns, errors)
|
|
3. **Module/package docs:** High-level purpose and usage
|
|
4. **README:** Setup, usage, examples
|
|
5. **Architecture docs:** System design, component interactions, use valid mermaid diagram
|
|
|
|
### Related Principles
|
|
- Core Design Principles @core-design-principles.md
|
|
- Code Organization Principles @code-organization-principles.md
|