We noticed the pattern in a codebase that was otherwise in good shape: comments that were confidently wrong, clustered around the files touched most often by a coding agent.
Why they rot faster
A comment written by a person describing intent tends to survive a refactor, because the person doing the refactor reads it and either keeps it true or deletes it. A comment written by a model describing current behaviour has no such relationship with intent. When the behaviour changes, nothing prompts anyone to revisit the sentence sitting above it, and it quietly becomes a lie that reads as documentation.
The kind of comment that causes damage
- "This returns null if the user has no orders" — true when written, false after someone added a default value three sprints later.
- "Called from the billing job only" — true once, false the day a second caller was added and nobody searched for the comment.
- A restated function name in prose, which was never true information and just adds a second thing to keep in sync with nothing.
None of these are wrong to write in the moment. They are wrong to leave unowned.
What we changed
We stopped asking agents to comment on behaviour and started asking them to comment on reasoning — why a non-obvious choice was made, not what the code currently does. Reasoning ages better because it does not depend on the mechanics staying the same.
A comment that restates the code will eventually contradict it. A comment that explains a decision only goes stale if the decision changes, and that is rare enough to be worth flagging when it happens.
The review question we added
During review, anyone can flag a comment as "describes behaviour, not reasoning" and it gets removed rather than fixed, on the basis that the code is already the source of truth for behaviour and a second, unmaintained copy of that truth is a liability.
Where we still want them
Comments explaining a workaround for a specific bug in a dependency, a business rule that looks arbitrary but isn't, or a decision that was reversed once and might be proposed again — these earn their keep because nothing else records them. We ask for more of these, not fewer, and we ask for them in full sentences rather than the clipped style a model defaults to.
What this cost us
Slightly more back-and-forth in review, because "explain why" is a harder instruction to satisfy than "explain what". The trade held: the files where we enforced this have measurably fewer comments that reviewers flag as wrong, six months on.