The Comment the Agent Called Stale Was Holding an Invariant
An agent doing a cleanup pass flagged a single-line comment near a function and asked whether to remove it. The surrounding code already said what the function did, so the comment looked redundant. It deleted the line, the suite stayed green, and the commit looked tidy. Two weeks later an ordinary change to that function broke a batch job, because the deleted comment was the only written record of why a value had to stay in a specific range.
That comment was never explaining the code. It was guarding a constraint the code itself could not express in the type system. Removing the prose did not change behavior today, but it removed the warning that stopped the next person, or the next agent, from editing the value freely.
Two kinds of comment, one looks like the other
| Comment kind | What it carries | Removing it today | What disappears |
|---|---|---|---|
| Restates what the code says | Noise readers already infer | Safe, code still passes | Nothing of value |
| Notes an edge condition or historical reason | Why a non-obvious choice was made | Code still compiles | The reason for the constraint |
| Flags a caller contract the signature does not show | Behavior assumed by upstream callers | Tests still pass | The assumption callers depend on |
| Marks a deliberate, unusual non-goal | What the code must never do | Build stays green | The boundary future edits cross |
The first row is what lint rules and "remove redundant comments" advice target. The rest often sit in the file looking identical: one line above a block, easy to misread as noise. An agent optimizing for a clean diff cannot tell which row it is deleting unless the comment itself states the reason, and even then it may treat that reason as expendable history rather than active guidance.
Why a green build does not catch this
The deletion compiles, because prose carries no executable signal. The existing tests cover the happy path the constraint lives just outside of. Nobody calls the broken batch job in CI every run, so the failure waits until a real input crosses the range the comment mentioned but the code no longer repeats.
This compounds across sessions. A fresh agent that never saw the original reasoning opens the function, sees no comment, and treats the value as a free parameter it can widen. There is no record to contradict it, and there is no failing test to stop the move before merge. The invariant was already fragile; the comment was the load-bearing part of it.
What to check before deleting a comment
When a cleanup pass touches a comment, the cheap move is to stop and ask why this line was written. A few questions sort the restatable kind from the load-bearing kind:
- Does the surrounding code already say this in plain sight, or is the comment filling a gap the types and names leave open?
- Is it describing the current behavior, or recording a past decision, a known caller, or a range that a test does not pin?
- If I remove it, would a reasonable editor today still understand why this value cannot move?
Where the answer lands on a constraint, keep the note or replace it with an executable guard the suite enforces: an assertion at the boundary, a named constant with a bound, or a test that fails when the range widens. Move the reason into a place the compiler or CI reads instead of deleting it outright.
Review catches the prose, not the reason behind it
A human reviewer glancing at a diff sees one removed line and rarely reconstructs the incident that produced it, especially late in a long review. The habit that helps is asking the agent, before it cleans a comment, to quote the reason back: what constraint does this line carry, and what breaks if it goes away? If it cannot name a concrete caller, edge, or historical reason, the line probably is noise and can go. If it can, the note belongs somewhere a future edit cannot miss.
Not every comment deserves to survive, and a file full of restated code is a real problem. The line that records a non-obvious constraint is the rare one worth keeping, and it tends to be the exact line a tidy pass removes first.
Where in your repo did a removed comment come back to bite you, and was it ever turned into a guard CI could read?