Comment Quality

Rules

GC-20 — WHY not WHAT, density

• "/* increment counter */" → delete (code says WHAT, comment must say WHY).
• Multi-paragraph essay / numbered plan comment → compress to 2-8 line WHY block. Link to issue/pr for long history, not in comment.
• Doc scaffolding /** @param on private/internal helper → downgrade to plain /* WHY block or delete. Reserve full doc for exported public APIs. Grep for name - summary + @param: to catch — scaffolding appears under both markers.
• 50-word para cap aim (see changelog GC-12) applies to comments too.

GC-21 — Placement, one source of truth at definition

• Doc comment lives at definition, not prototype/header when they differ. Header can have brief one-liner or none — deep WHY at def.
• Helper inserted? Doc left describing wrong function after insert still compiles — read for it.

GC-22 — Subtle logic MUST have WHY

Genuinely subtle logic with no WHY comment is a bug. Check:

• Locking / ordering / lifetime / invariant / barriering / ownership transfer.
• Security / validation decision: why safe here but not elsewhere.
• Concurrency: who serializes, what can race, what barrier pairs where.

If you can answer "why not simpler?" you need a comment.

GC-23 — Comment contradicted by a code change → rewrite in the same diff

Stale comment is worse than none, and a stale DOCSTRING is worse than a stale comment: a comment narrates, a docstring makes a contract — one naming a parameter, return key or field the code no longer has reads as an invitation to call something that is not there. Rank the drift by what the text claims, not by how close it sits to the edit.

• Radius is the identifier, not the neighbourhood. Removing a key, field, flag, function or config name is a rename in reverse: grep the WHOLE tree for that name — code, tests, docs, docstrings, comments — and settle every hit in the same commit (change-splitting GC-36 owns the completion evidence). The survivors are the ones no compiler reports: a docstring in the file you edited, or a comment in ANOTHER module that justified its own field by the removed thing.
• Write what is true now, not what was true. The replacement says why the code does what it does today; the retraction is history and belongs in the changelog, where a reader looking for it goes. GC-24 already bans provenance in shipped comments — a retraction note is provenance. A comment whose only justification was the removed thing is rewritten to that thing's own contract, or deleted.

GC-24 — Public-only context

Per upstream-hygiene: no private infra, no internal mount paths, no "this is like our fix in X" cross-project lore. If comment needs external pairing, name only upstream public symbols, e.g. "Pair with update_cache() — must hold lock per contract in cache.c".

GC-25 — Comment removal is cleanup, not fix — separate drive-by

Removing a long-wrong comment mixed with logic change inflates diff. Do: separate commit "Remove stale comment — no behavior change" or fold only when that stale comment explains logic you are changing now.

Anti-patterns

Positive framing for comments too

Applies from generic-principles "Positive framing". Comment that says "This is not kernel code" or "This is not X" is defining by negation — rewrite to what it IS and its contract. Provenance ("was previously ...") belongs in commit message or docs/references, not in code comment that ships.

Verification

Use placeholder tokens for verification examples (self-dogfoods upstream-hygiene).

# Stale pattern: probe nearby file for contradictory TODO
git diff --unified=0 | grep -A2 -B2 "TODO\|XXX\|HACK"
# Private leakage — real scanner lives in private overlay; skeleton here uses placeholder marker
git diff HEAD 2>/dev/null | grep -E "^\+\s*(//|#|/\*|\*)" | grep -i "example\.invalid" && echo "REVIEW: placeholder marker still present — strip or rewrite" || echo OK

Related

• code-structure owns helper extraction — this skill owns what comment moves with it.
• upstream-hygiene owns banned classes — this skill references it for examples.
• generic-principles Positive framing — where tagline rule encoded.
• project-discovery — sample the changesets of the files you touch for the project's comment style, terminology, and length.