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
Spec scenario a test covers	Yes — traceability token	[spec:<feature>#S<n>] in the test's description string; a one-line comment only when the framework has no description string (skills/shared/spec-gate/SKILL.md § Traceability)

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/references/type-annotations.md
Test files in scope (*.test.*, *_test.*, spec/)	skills/shared/comments-policy/references/aaa-pattern.md
Legacy code review or refactor task	skills/shared/comments-policy/references/anti-patterns.md
Greenfield development	None — core SKILL.md is sufficient

Reference Material (load on demand)

• references/aaa-pattern.md — AAA test pattern with examples
• references/type-annotations.md — type annotation rules by language
• references/anti-patterns.md — anti-pattern examples (what NOT to do)