clean-commentslisted

# Clean Comments Write comments and docstrings only when they add information the code cannot express clearly by itself. The goal is not fewer comments. The goal is higher information density: contracts, rationale, constraints, invariants, side effects, surprises. ## Core Principle Prefer this order — improve the code before adding a comment: 1. Clear names 2. Small, focused functions and classes 3. Type annotations 4. Constants instead of magic values 5. Assertions or validation for enforceable invariants 6. Docstrings for public contracts 7. Comments for non-obvious reasoning or constraints Never delete a comment that records a design decision, external constraint, security rule, concurrency assumption, or reason an obvious alternative is wrong — rewrite it more clearly instead. Git preserves history; comments preserve reasoning. ## Comment Rules (quick reference) Full rules with examples: [references/comments.md](references/comments.md) | Rule | One line | | --- | --- | | C1 No inappropriate info | No authors, dates, tickets, change history — that belongs to Git/issue trackers | | C2 Delete obsolete comments | A stale comment is worse than none; update docs in the same edit as the code | | C3 No redundant comments | Never restate what the code says; add semantics, not translation | | C4 Write comments well | Brief, specific, adjacent to the code, focused on why | | C5 No commented-out code | Delete it; Git preserves versions | | C6 Intent, not mechanics | Explain