| name | comments-policy |
| description | Code comments — none by default; type annotations and AAA markers. |
Comments Policy
The guiding principle: code should be self-documenting through clear naming. Comments are the exception, not the rule.
Core Principle — Default: No Comments
Code communicates intent through clear naming, small focused functions, and proper structure. Comments become outdated, double the maintenance burden, and often signal unclear code.
Before adding a comment, ask:
- Can I make the code clearer with a better name or extracted method?
- Is this explaining WHAT (fix the code) or WHY (only valid reason)?
- Is this a required type/exception annotation?
- Will this comment become outdated?
When NOT to Comment
| Anti-pattern | Rule |
|---|
| Explaining what code does | Improve the code instead |
| Commenting bad code | Fix the code instead |
| Noise / obvious annotations | Remove them |
| Commented-out dead code | Delete it — Git history exists |
| Version-control comments | Use Git commits |
| TODO / FIXME | Create an issue tracker ticket |
Dividers (// === Section ===) | Use proper class/method structure |
| Journal / attribution | Use Git blame |
Closing brace markers (} // end if) | Refactor to smaller functions |
See references/anti-patterns.md for full before/after code examples.
When to Comment
| Case | Required? | Format |
|---|
| Business rule or regulatory constraint | Yes — explains WHY | Inline comment citing the rule |
| Non-obvious algorithm with external reference | Yes — explains WHY | Inline comment with URL |
| Workaround for a known external bug | Yes — explains WHY | Inline comment with ticket reference |
| Typed collections / generics | Yes — type annotation | Native language syntax |
| Exceptions / errors thrown | Yes — type annotation | Native language syntax |
| ORM/dynamic property types | Yes — type annotation | Native language syntax |
| Complex return shapes | Yes — type annotation | Native language syntax |
| Test structure | Yes — AAA markers | // Arrange, // Act, // Assert |
See references/type-annotations.md and references/aaa-pattern.md for full examples.
Length Rule — Brief and Direct, Never a Block
When a comment is warranted (WHY, not WHAT), it must be short: 1 line as the default, 2–3 only when the constraint genuinely cannot be stated in one. State the rule/workaround/reference and stop — no restating of the surrounding code, no walkthrough of alternatives considered, no multi-paragraph rationale.
Hard limit: max 3 lines per comment, max 3 comments per contiguous block (e.g. per config section, per function). A comment that needs more than 3 lines to justify itself belongs in an ADR (docs/development/adrs/) or a commit message, referenced by a single short line — not inlined. This applies everywhere, not only source code: config files (nginx, YAML, Dockerfiles), infra scripts, and templates follow the same limit.
| Anti-pattern | Fix |
|---|
| Multi-line header block above a config section explaining history/context | One line stating the constraint; move the rest to an ADR or commit message |
| Walking through what was tried before landing on this line | Delete — Git history already has this |
| Repeating the same WHY across several adjacent lines | State it once, near the first line it applies to |
Quick Reference
Need to add a comment?
├─ Explaining WHAT code does? → ❌ Improve the code instead
├─ Explaining WHY (rule/workaround)? → ✅ Add it with context
├─ Type info the language can't express? → ✅ Required — use native syntax
├─ Exceptions / error conditions? → ✅ Required — use native syntax
└─ Test structure? → ✅ Required — use AAA markers
Language-Specific Style
Detect the project's primary language and load the corresponding section:
| Language | Load |
|---|
| JavaScript / TypeScript | sections/javascript-typescript.md |
| Python | sections/python.md |
| Go | sections/go.md |
| PHP, Ruby, Java, C#, Rust, or other | sections/generic.md |
If multiple languages are present, load the section for the dominant one (most source files).
Conditional Section Loading
Load relevant sections based on context — don't load all sections eagerly:
| Context | Load |
|---|
| Python files in scope | skills/shared/comments-policy/sections/type-annotations.md |
Test files in scope (*.test.*, *_test.*, spec/) | skills/shared/comments-policy/sections/aaa-pattern.md |
| Legacy code review or refactor task | skills/shared/comments-policy/sections/anti-patterns.md |
| Greenfield development | None — core SKILL.md is sufficient |
Reference Material (load on demand)
references/aaa-pattern.md — AAA test pattern with examplesreferences/type-annotations.md — type annotation rules by languagereferences/anti-patterns.md — anti-pattern examples (what NOT to do)
