A Wrong Comment Is Still A Bug

A comment that misdescribes what the code actually does is not a harmless documentation nit sitting next to a working feature. It is a bug that hasn't shipped yet, because the next engineer who touches that code will read the comment before they reread the logic, and they will build their change on top of the wrong mental model it hands them. I watched this play out clearly this week in a review of a small dashboard feature, and the resolution was more interesting than the original bug report would have suggested.

The feature itself was ordinary: a set of tiles showing how many records fell into each status, with each tile's count meant to sum to a visible total sitting above them. Somewhere in the code that built this total, a comment asserted a blanket rule — certain categories were always excluded from the count, full stop. That comment had been true when it was written, for the main view the feature was built for. But the same total-building logic was reused by a second, more specialised view, and in that second view the blanket rule the comment described wasn't actually how the numbers worked. One of the "always excluded" categories was, in that view, deliberately included, because the view broke it out into its own separate tile rather than dropping it. The reviewer flagged it as a discrepancy between the documented rule and the observed behaviour, which is the moment that usually splits into one of two very different outcomes.

The first outcome, and the more common one under time pressure, is to assume the code is wrong because the comment says something specific and confident, and confidence reads as authority. Someone "fixes" the number to match what the comment promised, ships it, and quietly breaks the one case the comment never anticipated. The second outcome, the one that actually happened here, is slower and more useful: trace the arithmetic itself before trusting either the comment or your first instinct about which one must be at fault. When that tracing was done properly, the total in the specialised view turned out to be exactly right. The category the comment claimed was always excluded needed to be included there, specifically because that view gave it its own tile — and if it had been excluded from the total the way the comment insisted, the tiles would have summed to less than the number displayed above them. The code had it correct. The comment was simply describing a rule that only ever applied to one of the two places it governed.

That distinction matters more than it looks like it should, because "the code is right, the comment is wrong" sounds like a non-event, the kind of thing you'd wave off with a one-line documentation fix and move on. Treating it that way misses what actually happened here: a false claim about system behaviour had been sitting in the codebase, unchallenged, until someone needed the total to add up correctly and went looking for proof rather than accepting the explanation on offer. If that person had trusted the comment instead of the arithmetic, the fix they'd have shipped would have been a real regression, introduced specifically because a document written to prevent mistakes had become the thing causing one. A wrong comment doesn't sit inertly next to correct code. It actively misinforms the next decision made near it, and the more confidently it's worded, the more damage it does when it's wrong, because confident wording is exactly what makes people stop checking.

The fix that shipped had two parts, and both mattered. The comment was corrected to describe what was actually true — the exclusion rule held for the general case and did not hold for the specialised view, and the reason it didn't hold was explained rather than just noted, so the next reader would understand why the exception existed instead of just that it did. And a new test was added that didn't re-check the exclusion rule in isolation, but asserted the invariant that actually mattered: the tile counts, summed, equal the total displayed above them, checked specifically under the conditions of the specialised view where the old comment would have predicted a mismatch. That second part is the piece worth remembering independently of the documentation fix. A test that checks "this category is excluded" only tells you the rule was followed. A test that checks "the parts sum to the whole" tells you the system is actually consistent, regardless of which specific rule produced that consistency. The invariant is what you actually care about; the exclusion rule was only ever one particular way of trying to guarantee it.

The broader habit worth taking from this isn't "proofread your comments," which is true but not actionable enough to change anything. It's that a discrepancy between a comment and observed behaviour is genuinely ambiguous evidence, and it deserves the same investigative respect as a customer bug report, not a reflexive assumption in either direction. I've seen engineers assume the code must be wrong because the comment sounds deliberate, and I've seen the opposite mistake too — assuming a comment is stale and deleting it without checking whether it was actually protecting something real. Both are shortcuts around the one step that actually resolves the ambiguity, which is going back to first principles and working out what the system is supposed to guarantee, then checking which of the two conflicting sources — the words or the code — is telling the truth about that guarantee.

There's a trust dimension underneath this that's easy to underweight. Comments exist because reading raw logic is slow, and teams rely on them precisely so that not every person has to re-derive every rule from scratch every time they touch adjacent code. That convenience is only safe if the comments are held to the same standard as the code itself — reviewed, corrected, and treated as claims that can be wrong, rather than as settled fact once they've been written. A codebase where comments are assumed accurate by default and never re-verified against behaviour is a codebase quietly accumulating a second, unversioned copy of its own logic, one that nobody is testing and everybody is trusting. The fix here took one paragraph and one test. Finding it took someone willing to disbelieve a sentence that sounded completely reasonable, and go check.