Sweep Comments

Sweep comments

Every comment must state a constraint the code itself cannot show, in one short sentence. If deleting the comment loses nothing a maintainer needs, delete it. Thoroughness is accuracy, not volume: an accurate, lean file is stronger in review than one padded with restatements.

The reader

Write for the reader you actually have: a professional who is competent at reading code and willing to learn the context on their own. They can read a call signature, follow a loop, and look up a library. Comments exist to hand them the facts they cannot get that way — not to tutor them through the language, the stdlib, or the control flow. Assuming an incompetent reader is what produces restatement comments; assuming this reader is what keeps them out.

The bar

A comment earns its place only if it says something you cannot get by reading the statement below it. Hold every comment — new or existing — to this test.

Keep (these say what the code cannot):

• Behavioral constraints of external tools and systems, e.g. a flag chosen because of a filesystem cache pathology, a layout-engine quirk, a protocol quirk.
• The why behind magic values: weights, thresholds, limits, ports.
• Schema documentation on data tables and wire formats.
• Source-of-truth pointers ("the registry in X is authoritative").
• A deliberate absence ("no retry here on purpose; rsync --partial handles resumption").

Delete (these repeat what the code already shows):

• Restatements of the next line ("Build the command", "Loop over the files in sorted order", "Get the service id from the environment").
• Literal readings of a call — describing what os.environ.get or a four-line function does in prose.
• Process narration and war stories: how the fix was found, what the code used to do, why this change is correct. That is PR-description material, not a comment.
• Derivation walkthroughs. State the constraint or invariant in one sentence; do not teach the algebra line by line.

Examples that do not survive

Each of these was found in a real pre-PR sweep (identifiers genericized). The pattern, not the wording, is what to recognize:

• # Defaults to "primary" but honors SERVICE_ID from the environment above an os.environ.get("SERVICE_ID", "primary") — a literal reading of the call. What survived instead: the one fact the code could not show (which config layer wins when both are set).
• A four-line comment above a four-line classification function, paraphrasing its branches almost word for word. Deleted outright.
• # Entries stack above their group's anchor row on a list literal whose ordering already shows exactly that. The list is the statement; the comment is an echo.
• A comment justifying a layout mechanism "because auxiliary edges do not constrain placement" — auxiliary edges had been deleted a dozen iterations earlier. Stale rationale from a design pivot; rewritten to the mechanism's actual current purpose.
• A four-line header on an enum-to-role table re-describing enum names that are self-descriptive. Shrunk to the single surviving fact: the one non-obvious classification decision.
• "After several failed attempts we discovered that the renderer ignores these edges during coordinate assignment" — the constraint (renderer ignores them) survives in one sentence; the journey does not.

Writing new comments

• One short sentence per constraint. If a comment needs a second sentence, check whether it is carrying a second (or zero-th) fact.
• Never mix a restatement with a real fact to justify the comment. Split off the fact and delete the restatement half.
• Match docstring weight to audience: a public API earns parameter docs; a ten-line internal helper earns one line stating purpose, not an Args/Returns block.
• Name specifics, not categories ("the vessel_command edge", not "the relevant edge").
• When a comment enumerates parallel facts — several name mappings, per-case rationales, a set of invariants — format it as a bullet list, one fact per bullet, rather than packing the enumeration into prose. Readers scan lists; they re-read packed sentences. The one-short-sentence rule then applies per bullet.
• Do not pad a file with comments to appease an "under-documented" complaint — reviewers are protected by every comment being true and non-obvious, not by comment count.
• Never invent a rationale for a value whose reason you do not know. A wrong why-comment is worse than none.