Sweep Comments

Sweep comments

Comment placement is a design question before it is a hygiene question. Ask "where does the reader need this to be understood?" before "should this comment exist?" — a sprinkled explanation is usually a symptom that the design was never taught in one place, so every dependent site grew a defensive footnote. Thoroughness is accuracy, not volume: an accurate, lean file is stronger in review than one padded with restatements.

The two readers

A comment is read by a human and by a coding agent, and it must serve both. They differ in exactly one way that matters here, and the whole of this skill's placement rule follows from it.

The human is 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, look up a library, and derive what the language's own rules guarantee. They arrive through the file: module doc first, then the internals. A reader who did not read the code is not a reader the codebase serves — their confusion is not grounds for a comment. Assuming an incompetent reader is what produces restatement comments.

The coding agent has that same competence and none of that reading order. It arrives at a function by grep or symbol lookup, holding that function and little else, and it edits confidently on that much. It has usually not read the module doc, and a pointer costs it a retrieval it may not spend.

The competence bar is shared, so tier 1 dies for both: a restatement wastes a human's attention and burns the context an agent needed for the code itself. Verbosity is not agent-friendly; it is the tax both readers pay.

The reading order is not shared, and that is the entire difference. It changes nothing about what is worth saying and one thing about where: a fact that constrains edits must be legible at the site where a wrong edit would be made, not only at the model home.

Explanation follows the architecture

Software design is hierarchical — system, subsystem, type, function — and each level makes decisions the levels below inherit. Explanation mirrors that contour: every fact lives at the narrowest scope within which it is invariant, the level where its decision was made. The crate doc teaches the system model; a module doc its subsystem's protocol; a type doc the type's invariants; a method doc the call contract; inline comments the point facts. Misplacement fails in both directions: a fact repeated below its level is an echo, and a fact hoisted above its level — a module doc narrating one method's edge case — taxes every reader of the level and goes stale when that one method changes. If no level exists where a fact is invariant, that is a design smell, not a commenting problem.

Code materializes the leaves of that tree completely, which is why comments have value at every altitude above the code and none at zero: a comment at the code's own level restates what is already materialized, while prose is the only medium that can state the interior nodes — intent, models, protocols, why. The two media trade in opposite directions: code must be functionally sound and so cannot be vague — it is forced to total precision at the leaf level — while prose is licensed to abstract and omit, which is exactly what lets it serve one idea at different levels of detail. A comment competing with the code on precision is a restatement; choose its altitude instead.

The model home

Each subsystem designates one home — usually its module or crate doc — that teaches the mental model: the execution order, the ownership protocol, the invariants everything downstream leans on. State the model there once and fully. Downstream sites then hold only four kinds of comment:

• Externals — tier-3 facts (below) that no model statement can absorb, kept at their point of use.
• Deviations — places where the code does something the model would not predict. A reader carrying the model is more surprised there, so the local note earns its place.
• Edit constraints — the one clause of the model this site can silently break. Stated here as well as at the home, because the reader who breaks it is the one who never saw the home.
• Pointers — one clause directing the reader to the model's home, at sites distant enough that the association is not obvious.

An echo — a restatement of the model at a downstream site — is a delete, however true it is and however keeper-shaped its topic sounds. One authoritative statement plus pointers; never two copies drifting independently. An echo clause inside an otherwise-kept sentence is still an echo: split the sentence, keep only the underivable clause, and recompose it to stand alone ("cut whole sentences" protects meaning, not echoes).

The retrieval test

An edit constraint is the one case where two copies are correct, so it needs a test sharp enough that it cannot swallow the echo rule. Before reducing any downstream comment to a pointer, ask:

If a reader saw this site and nothing else, could they make a wrong edit here that the model would have prevented — and would it compile and pass?

If yes, it is an edit constraint: keep one sentence here, stating what must stay true, and leave the reasoning at the home. If no, it is an echo and it goes.

Qualifying facts are narrow and recognizable:

• What sharing a handle actually shares — a clone that aliases rather than copies.
• An invariant another file's logic leans on: a sequence that is dense from 1, a buffer already sorted, a field never empty.
• An ordering the code cannot express: this store must follow that push; this lock must outlive that read.
• A teardown or lifetime obligation with no destructor to enforce it.

Not edit constraints: performance characteristics, anything the type system or borrow checker already rejects, and restatements of the model's rationale rather than its requirement. A wrong edit there does not compile, or does not matter.

The form the model takes

Placement decides where a fact goes; form decides what shape it arrives in. The model home is the one place worth deciding form deliberately, because it is the only place whose job is comprehension.

Prose is linear, which makes it good at causation, obligation, and sequence — and bad at topology (what connects to what), layering (what sits above what), and simultaneity (what happens at once). Where the model is a shape, a paragraph makes every reader rebuild that shape in their head, one at a time, forever. The trigger is not how complex the design is; it is: must the reader construct a picture to follow this? If so, supply the picture.

Pick the lightest form that carries the shape, because form is maintenance:

• An ordered list or table — enumerable structure: what a module contains, what to read first, which error means what.
• ASCII — a small pipeline or sequence, roughly three to six nodes. It lives inline in the doc comment, needs no build step, and diffs as text.
• A diagram (D2 here) — real topology: many nodes, crossing edges, layers. It costs a separate file and a build step, so it must earn them.

Prefer forms whose source is the artifact. A rendered image is readable by the human half of the readership and opaque to the other half, while ASCII and D2 source are legible to both and reviewable in a diff. A checked-in image blob with no source beside it is a diagram only some of your readers have.

When the shape cannot live in the code

A doc comment can hold a list or ASCII; it cannot render D2. A model whose best form is a diagram therefore lives on a docs page, with the module doc holding a pointer.

That split is safe for comprehension and unsafe for constraint. A reader who never opens the page loses the picture but breaks nothing — whereas an edit constraint stranded on the far side of that pointer is exactly the failure the retrieval test exists to catch. Shapes may live one hop away; requirements may not.

Diagrams that do not survive

• One that shows what a single sentence already says — tier 1 in picture form, and dearer to keep true.
• One mirroring structure the code already materializes: a type hierarchy, a module tree, a call graph. The compiler and the file tree state those, and the drawing will drift from them.
• One kept because it was expensive to draw.

A diagram earns its place by showing what no single file materializes: flow across modules, a protocol over time, a layering. Sweep diagrams for staleness exactly as you sweep prose — a stale picture reads as more authoritative than a stale paragraph, so it misleads harder.

The bar: three tiers by derivation cost

Classify every comment by what it would cost the reader to reconstruct its fact from the code plus the language's own semantics:

1. Locally derivable — the fact is visible at the point of reading. Never comment it. This covers restatements of the next line, literal readings of a call, derivation walkthroughs of visible algebra — and topic is no defense: a Relaxed ordering justified by an exclusive lock held in the same function is generic language knowledge the reader owns.
2. Derivable at a distance — true, but reconstructing it means enumerating call sites or reading across files (a crate-private protocol, a cross-module invariant). Do not cache it at each site; state it once at the model home and reduce every echo to a pointer or nothing — unless the site passes the retrieval test above, which is the one carve-out: an edit constraint is stated at the home and in one sentence at the site that can break it.
3. Underivable in principle — the fact comes from outside the code entirely. This is the never-delete floor, kept at point of use, one sentence each:
   • External-system behavior and vendor quirks (a filesystem cache pathology, a layout-engine rule, a protocol convention).
   • Measured values and the why behind magic numbers: 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; the transport's watermark handles resumption").
   • Forward design commitments ("a parallel executor must preserve this invariant") — promises about code that does not exist yet.

Writing new comments

The cheapest form that carries the fact

technical-prose owns the general ladder and the reason it works. This is its comment-specific rungs: the tiers decide whether a fact is stated, these decide what it costs once it is. Stop at the first rung that carries the fact intact.

1. No comment. The tiers already ruled: locally derivable is deleted, and an echo of a distant model becomes a pointer or nothing.
2. A name. A fact a rename carries is not a comment. retry_after_ms needs no comment giving the unit, and a comment that exists to explain a name is a bug report against the name. This is the rung most often skipped, because renaming is work and a comment is not.
3. Trailing, on the line it qualifies. A fact binding one line rides on that line, where it cannot drift away from what it describes and the reader meets it with the line under their eye.
4. One line above. For a fact binding a block rather than a line, or a trailing form that would push the line past the column limit.
5. A doc paragraph on the item. For a contract a caller reads without reading the body: parameters, errors, panics.
6. The model home. Prose explaining a shape, stated once, pointed at from everywhere else.

Rungs 3 and 4 are where most comments belong and where few of them sit.

A rung is available only if the fact survives it intact. Modality, the subject of a claim, negations, and scope qualifiers do not compress onto a trailing comment merely because the line has room. When they will not fit, take the next rung up.

Prefer the fragment

A comment is a label on code, not prose to be read aloud, and the declaration beneath it already supplies the subject. Write the shortest form that carries the fact:

• /// Wrong source_id. Separate from type_mismatch so a misaddressed reader stays self-diagnosing.
• not /// Records whose source_idwas not the expected one. Kept separate fromtype_mismatch so that the misaddressed-reader case stays self-diagnosing rather than being folded into a generic bucket.

Grammatical completeness is not the bar; unmistakable meaning in context is. The gain is uneven by altitude and that is the point: field and variant docs are labels and shorten the most, method contracts shorten some, and a model home is prose doing real explanatory work — it tightens but stays sentences.

Two things a fragment may never drop. Both are ways a shorter comment says something different rather than something briefer:

• Modality. "Nothing may be moved out of it here" is a prohibition binding future edits; "nothing moved out here" merely describes the present and licenses the edit the comment existed to prevent. Every edit constraint keeps its must, may not, or never.
• The subject of a claim. "The operational response to any of them converges on one question" is not "all three converge on one question" — the first is about what an operator does, the second about the causes. Dropping a noun to save a line silently reassigns what the sentence is about.

Also survivable only as full sentences: negations, scope qualifiers (only, at most, never), and conditionals whose antecedent carries the constraint. When a fragment cannot keep these, write the sentence.

The rest

technical-prose is the home for modality, empty vocabulary, one-name-per-thing, and the ladder of how much to write; use it directly when the problem is wording rather than placement. It disclaims fragment versus sentence, which is why the fragment rule above can stand against a standard that would otherwise demand full grammar. The modality requirement is stated in both places on purpose: it is an edit constraint, and the reader shortening a comment here is the one who never opened that skill.

The bullets below are what comment writing adds on top of that bar:

• One short constraint per comment. A kept comment carrying more than one must justify each as a distinct tier-2-at-home or tier-3 fact; connective tissue, illustrative examples, and rhetorical elaboration ("cheap is not free", storm-and-stall vignettes) do not survive.
• Compress, don't paraphrase: compression must not change meaning. A guarantee ("never steps backwards") must not become an obligation ("must not regress"); when in doubt, keep the original wording and cut whole sentences instead.
• Never mix a restatement with a real fact to justify the comment. Keep the real clause, delete the restatement half.
• A docstring longer than the function it documents is an action trigger, not a style note: cut it down, or justify it. The public-API allowance covers parameter, error, and panic contracts — not essays.
• When a comment enumerates parallel facts, format it as a bullet list, one fact per bullet; the one-sentence rule applies per bullet.
• Name specifics, not categories ("the vessel_command edge", not "the relevant edge").
• Do not pad a file with comments to appease an "under-documented" complaint, and never invent a rationale for a value whose reason you do not know — a wrong why-comment is worse than none.

Examples that do not survive

Genericized from real sweeps; recognize the pattern, not the wording:

• # Defaults to "primary" but honors SERVICE_ID from the environment above the os.environ.get call — locally derivable (tier 1). What survived: which config layer wins when both are set (tier 3).
• A Relaxed justification reading "the lock's release/acquire edges already order these accesses" in a function that visibly holds the exclusive lock — tier 1, deleted; the reader owns the memory model.
• A type doc repeating the module doc's ownership protocol ("only the executor stores to it, between rounds, so the bound is immutable for the whole of one call") — the rationale is an echo of the model home and goes. The requirement passes the retrieval test and stays as one sentence: a store added anywhere else compiles and quietly moves a bound out from under a reader. Split the sentence; keep the half that constrains an edit.
• A four-line comment above a four-line classification function, paraphrasing its branches — deleted outright.
• A comment justifying a layout mechanism "because auxiliary edges do not constrain placement" after auxiliary edges were deleted — stale rationale from a design pivot, rewritten to the current truth.
• "After several failed attempts we discovered that the renderer ignores these edges during coordinate assignment" — the constraint survives in one sentence; the journey does not.
• A test's direction note reading "the reverse direction is not testable yet: no producer attaches metadata to its message stream" — false when written and false when reworded, since four producers did and a sibling test forwarded one of their message streams. Corrected to the truth, and the claim it made became a second test rather than a sentence.
• A field doc reading "the hosts that read this message stream" over a list of hosts on which nothing read it — they consumed the data over another transport, and the list staged the path they would move to. Rewritten as the forward-looking claim it was: "hosts a process on which consumes the message stream's data, by whatever transport carries it today; naming them stages the message stream they will read once they move."
• A fixture helper documented as producing metadata "the real producer could have written", beside an emit that hardcoded the message kind and invented the source id — either every field comes from the registry entry, or the claim goes.

Tests are labeled, not explained

A test is a leaf-level artifact pinning an interior-node claim, and its comments serve failure diagnosis, not comprehension. Hold them to a different bar:

• A test's doc comment states the property the test pins, in one sentence — and it may restate the model clause it enforces. Across the code/test boundary a restatement is a claim binding, not an echo: when the test fails, it names the promise that broke, which is the first thing a red CI run needs. The echo rule applies within load-bearing code, not from code to its tests. Both readers depend on this, and an agent triaging a failure has little else.
• Scenario-contrivance comments are keepers: the why behind a deliberately odd fixture — a capacity below the append count, a scripted failure on the second send — is tier 3 at point of use. Without it the contrivance reads as arbitrary and gets "simplified" away along with the coverage it existed to create.
• What still dies in tests: narration of the mechanics ("stage one sample and open the round"), restating the test's own name, and derivation walkthroughs.
• Demo and tutorial files are designated teaching sites: pedagogy is their function, so hold them to "teaches each idea once, clearly" rather than to the production bar.

The pre-PR sweep

Design pivots during a working session are the main source of lying comments: a comment written for iteration 3 still sitting on the code of iteration 12. Before opening or updating a PR:

Do the sweep yourself, in one context. Do not partition it across subagents. Whether a comment earns its place depends on the model home, the neighboring comments, and the session's pivots — context no per-file delegate has. If the diff is large, sweep it in one pass anyway; reading the whole diff is what the sweep is.

The sweep runs as two passes with opposite polarity, and they are not interleaved. One pass removes and the other restores; trying to do both at once means judging every borderline comment under a frame that wants it gone, and the frame wins.

Setup, before reading a single comment:

1. Partition the touched files by which bar applies: production, test, demo. Write it down first. A file read under the wrong bar gets the wrong rule applied to every comment in it, and no later carve-out recovers it — the production bar deletes a test's claim bindings before it occurs to you that a different bar was owed.

2. Build the model inventory: list every design principle the touched code relies on — not only the ones it states — and assign each a home and a form. A principle with no assigned home leaves every copy of it looking like a local keeper. If a model is stated nowhere, that is the first fix. Recording the form is what stops every model defaulting to prose; see below for choosing one.

   Inventory the subsystem, not the changed lines. A diff does not contain its own model homes, and any change adding a consumer of existing code has most of its models homed elsewhere: a parent branch, a dependency crate, a module doc the change never touched. Write down where each is stated and whether that file is in this diff; anything homed outside it makes every statement inside the diff an echo until the retrieval test says otherwise. Skip this and the diff reads as full of local keepers, because from inside it that is exactly what they look like.

Pass 1 — subtract. Classify every comment and docstring into a tier against the inventory. Tier 1 is deleted; tier 2 lives only at the home, echoes become pointers or nothing; tier 3 is kept and compressed to one sentence per fact. Then check each survivor against the current design, not the design it was written for: a comment referring to anything deleted or renamed is rewritten to the truth or deleted.

Then check each survivor's claims against the code, not the design. The staleness check above catches a comment that names something deleted or renamed. It does not catch a comment that names nothing deleted and is wrong anyway, and neither does anything in the tiers: a false claim can be well placed, tersely worded, and not an echo. For every kept or written comment, list the claims a reader could verify and verify each with one grep or one test name, against the code as it is:

• Claims of absence or exclusivity — "no X yet", "only Y", "nothing else does Z". These age fastest and are the ones a reviewer catches: a note that "no producer attaches metadata yet" survived a rewrite in a crate whose own test asserted that one did.
• Claims of equivalence — "the same as", "mirrors", "looks like the one the real writer produces". Check every field the claim covers: a fixture described as "metadata the real producer could have written" took its payload type from the registry and still hardcoded the message kind and an invented source id.
• Present-tense claims about who does what — "reads", "consumes", "forwards", "subscribes". A field documented as "hosts that read this message stream" named hosts on which nothing read it; they consumed the same data over a different transport, and the list was staging a path they had not yet moved to. A claim about the future is written as one.

An inherited comment being rewritten gets the same check as a new one. Rewording carries the old claims forward under new authority, so a false one gets worse, not better; the prose pass finds needless words, never false ones.

Report pass 1 as one line per finding, so the sweep can be checked without re-reading the diff:

<file>:<line>: <tag> <what it said>. <what stands there now>.

Tags are the dispositions: drop for a tier-1 deletion with no replacement, point for an echo reduced to a pointer at its home, shrink for a survivor compressed, inline for one moved onto the line it qualifies, rename for one deleted because a name now carries it, correct for a claim the code contradicted, rewritten to what the code does, and keep for a tier-3 fact left alone. Close with the count: net: -N comment lines.

A diff with nothing to cut says so in the same form — "no tier 1 or 2 comments in the touched files" is a claim, and a claim can be wrong, which is what makes it worth more than silence.

Pass 2 — restore. Walk the edit sites — every place a future change could land, not every place a comment currently sits — and at each one ask the retrieval test: could a reader who saw this site and nothing else make a wrong edit here that still compiles and passes?

This pass may only keep or add. It is not a review of pass 1 and it does not re-litigate a deletion on taste; it asks one question and acts on the answer.

Its output is a written list of the sites that passed the test and the one sentence each now carries. An empty list is a failed pass, not a clean bill — a diff that touches load-bearing code has edit constraints in it, and finding none means the test was not actually run. Report the list with the sweep.

Then:

3. Check the commit message, the module docstring, and any diagram the touched code is drawn in — all three go stale on the same pivots, and the diagram is the one nobody thinks to open.
4. Verify the sweep was purely editorial: tests still pass, and any generated output (code generation, DOT/SVG, fixtures) is byte-identical before and after.

Rationalizations

Comments that should not be written at all

Some comments fail at write time, regardless of wording — the content has a home, and it is not the code:

• Change-narration ("fixed the off-by-one", "added guard") — the commit message and PR description exist for this; in code it becomes a "previously" red flag the moment it lands.
• Commented-out code kept "in case we need it back" — git history is the fallback: reverting a commit beats resurrecting a block that has rotted against the surrounding code.
• Idle TODOs — a TODO with no ticket, owner, or design commitment is a musing that ships as a stale comment with authority. File the ticket or drop the thought. (A forward design commitment — tier 3 — is different: it binds future code to an invariant.)
• Banner comments (// ---- helpers ----) — writing-session scaffolding that carries zero facts. A file that needs banners wants to be split into modules instead.
• Linter-appeasement docstrings on trivial internals — suppress the check at the site and fix the config; a machine's "under-documented" complaint licenses tier-1 prose no more than a human's does.
• Insurance comments written to pre-empt or placate a reviewer — answer in the review thread and strengthen the model home; a comment written to end a conversation serves the wrong reader.
• Guessed rationales — never write a why you do not actually know.

Red flags — stop and re-check

• The same model stated in more than one place.
• A multi-subsystem diff swept against a single model home: the sweep anchored on the model you already knew.
• A model inventory whose homes are all inside the diff, on a change that adds a consumer of existing code — that is a sweep that never looked up from the diff.
• A comment whose fact a competent reader could derive from the code in front of them plus the language's own rules.
• A comment beginning with what the next line literally does.
• A docstring longer than the function it documents.
• "Previously", "used to", "we changed this to" in a comment.
• A comment you are keeping because deleting it feels like losing work — or because its topic sounds important.
• A sweep plan that contains the word "delegate", "fan out", or "per-file subagent".
• Commented-out code, a ticketless TODO, or a section banner in a diff you are about to ship.
• A comment you are writing mainly so a reviewer or linter stops asking — not because the reader at that site needs the fact.
• A tier-2 fact reduced to a pointer without asking whether an edit at that site could break it and still compile.
• A sweep whose diff is deletions only: the retrieval test keeps things, and a sweep that kept nothing probably never ran it.
• Pass 2 folded into pass 1 "to save a read", or run as a re-read of pass 1's deletions rather than a walk of the edit sites.
• A test or demo file swept before the bars were partitioned.
• A model inventory whose every entry has the form "prose": the form column was filled in after the fact, not chosen.
• A paragraph at a model home that names three or more components and the connections between them — that is a shape being spelled out.
• An edit constraint reachable only by following a link to a diagram.
• An "edit constraint" you are keeping whose violation the compiler would catch — that is the carve-out being used as an excuse.
• An edit constraint with no must, may not, or never in it.
• A shortened comment whose grammatical subject differs from the one it replaced.
• A shortened comment that dropped only, at most, or a negation.
• A model home rewritten into fragments: explanation is the one place prose is doing the work.
• A comment above a line whose fact binds that line alone.
• A comment whose job is to explain the name directly beneath it.
• A block comment that survived because it was already a block, rather than because a shorter rung would have lost something.
• A trailing comment that dropped a must, a never, or an only to fit the column limit.
• A pass-1 report that is prose rather than one line per finding, so a reader cannot tell which comments were touched.
• A comment saying "no", "only", "nothing else", "the same as", or "looks like" whose claim was not checked with a grep before the sweep kept it.
• A rewritten comment whose claims were inherited from the old one and never re-verified.
• A present-tense "reads", "consumes", or "subscribes" over code where the named party does no such thing yet.