Comment Lint

comment-lint — acting on the devlog-comment report

Drives scripts/lint.lg, the report-only scan for comments that narrate a change instead of describing the code. The script decides what to look at; everything below is the judgement it deliberately leaves out. Rationale and the open phrase-list questions: nooga/let-go#835.

How to run

From the repository root:

lg scripts/lint.lg                  # default: pkg scripts
lg scripts/lint.lg pkg scripts cmd  # widen the scan

Report-only. It never edits source, and findings do not affect the exit status (a run that finds 13 things still exits 0), so a hit is never a build gate and never an instruction on its own.

What a hit means

A hit flags a comment block to re-read, not a phrase to delete. The phrase list matches tense markers — "used to be", "moved from", "this PR" — because those are cheap to match and rarely appear in a description of working code. The thing being flagged is the narration underneath, which can survive any edit that only removes the matched words.

So the linter going quiet is not the goal. The goal is a comment that a reader who has never seen a previous version of the file can use.

The test

Would this sentence still be true and useful to someone reading this file for the first time, who has no idea it was ever different?

If removing the comparison leaves the sentence incomplete, the comparison was history and the sentence needs rewriting, not trimming.

Counterfactual, yes; historical contrast, no

These two look alike and are not alike.

Counterfactual — keep. What goes wrong without the code as it stands. This is the honest content of most regression-test and benchmark comments, and it is frequently the right rewrite:

// derefSink defeats dead-code elimination: without a package-level sink the
// compiler may elide the Deref call entirely, producing impossible sub-ns
// numbers that say nothing about the real cost.

A reader can check that against the code in front of them, and nothing in it needs a previous version of the file to parse.

Historical contrast — rewrite. The previous design, re-tensed. The giveaway words are rather than, instead, not X but Y, alone could do without, only got away without:

// It is passed to the module scaffolder rather than baked in, because the
// AOT native path shares that code.

rather than baked in only parses if you know it was once baked in. The second clause is subtler, and it is the reason the rule above exists: the AOT rationale is true — pkg/gomod's package doc states it, naming #596 and the three behaviors — but it is a fact about pkg/gomod, already written on pkg/gomod. Restating it on a constant in pkg/cli is a second copy that only the change's author would think to put there. When a kept claim checks out, ask where it already lives before keeping it here.

Removing the flagged phrase without removing the history is the failure mode this skill exists to prevent. It passes the linter and changes nothing for the reader.

A counterfactual is not automatically correct

Passing the test above does not make a sentence true. A rewrite that keeps the old comment's shape keeps its claims, and the claims are the part most likely to have gone stale:

// asBytes backs the binary file/stream sinks (spit, write!). The byte-array
// case is the one that needs it: without the coercion, a byte-array handed to
// spit/write! stringifies to its #byte-array[…] repr, so bytes >127 never
// reach the sink.

Two defects, neither of them visible to the linter. The stringify claim is true of write! — iort.go falls back to vs[1].String() — and false of spit, which returns spit expected String or byte-array rather than writing anything. One sentence asserts one behavior for two callers that do different things. And where the claim does hold, iort.go already states it on the code itself, so repeating it on a test is the second-copy defect from the wasm.go case above.

Rewrite from the function instead: it converts a String or a byte-kind TypedArray and rejects everything else. That is checkable in one place and stays true whatever the callers do next.

Rewrite or delete

Do not assume every flagged comment has a salvageable core. Three outcomes, in rough order of frequency:

1. Trim. The narration is a clause on an otherwise good comment. Drop the clause. (the miscompile this PR fixes → the miscompile.)
2. Delete the comment. What remains is a fact about the code's history that a reader of this file does not need, or a forwarding address to code that is already reachable by name. A pointer saying four helpers "moved to" another namespace tells a reader of the file they left nothing about the file they are in.
3. Rewrite from the code. The comment records something real — an invariant, a hazard, why an obvious simpler form is wrong — stated as history. Re-derive it by reading the code, not by re-tensing the sentence.

Every causal claim you keep must name code you can point at. A rewrite inherits the old comment's assertions, and those were true of a tree that has moved. Before keeping "because X shares this" or "so that Y can Z", find X and Y in the current tree — repository-wide, including tests and build-tagged files, not just the package in front of you. If you cannot, the claim is history and goes; if you can, check whether the place it is already documented is a better home than this one.

Outcome 3 is where accuracy slips. A comment written as history was true of code that no longer exists, so its details can be stale in ways the linter cannot see: a benchmark comment naming the fields root and curr survived a rename to root and rootBind, and re-tensing it would have preserved the wrong names. Read the code before rewriting; do not paraphrase the old comment.