Comments

Comments explaining what the next block of code does, what a function returns, or how a parameter is meant to be used.

Comments explaining what the next block does or what a function returns; the agent loading the comment plus the code carries two sources of truth that may have drifted apart.

Names of functions, variables, and types tell the reader what the comment was trying to say. Comments survive only when WHY is non-obvious.

Names tell the agent what the comment was trying to say; comments survive only when they document a non-obvious WHY (hidden constraint, invariant, workaround).

The code didn't reveal its intent — the comment is patching an unnamed function or unclear variable; comment and code drift over time.

The code didn't reveal its intent so the comment is patching an unnamed function or unclear variable; the agent must reconcile both sources and risk acting on the stale one.

Renaming to express what a comment said increases churn across consumers and history; some legitimate comments (non-obvious WHY, hidden invariants, workaround references) are harder to convey through names alone.

Renaming to express the comment's content ripples across consumers (cross-repo greps, embedding indexes, prior conversation context) the agent must accept will drift stale for a window.

No more stale comments; readers trust names; reading the code is the path to the answer.

Naming carries the intent directly; the agent reads one symbol to predict behavior instead of loading both the symbol and the comment and reconciling any disagreement between them.

Deleting every comment as part of a cleanup pass — including ones that document hidden constraints, historical context, or invariants that names genuinely can't express.

Deleting every comment in a cleanup pass — including ones documenting hidden constraints, historical context, or invariants names can't express — strips load-bearing context the agent will need later.