Comments Should Explain Why, Not What

The Comment That Says Nothing

// Increment counter by one
counter += 1;

I have read this comment, in some form, in every codebase I’ve ever worked in.

It tells me nothing the line beneath it doesn’t already say, in fewer characters, with less ambiguity. It’s noise. And it’s the specific kind of noise that goes stale: somebody changes the increment to two, the comment stays as it is, and now the file contains a small lie that will waste somebody’s afternoon in about eighteen months.

One Word Changed

// Offset by one because the API uses 1-based indexing
counter += 1;

That’s the same line of code and a completely different comment. Now I know something I could not possibly have worked out from reading the code, no matter how carefully.

More importantly, it answers a question I was about to ask. “Why is this here?” is the thought that stops people mid-scroll, and a comment that arrives exactly at that moment is worth ten that narrate the obvious.

What Code Genuinely Cannot Tell You

Good code handles the what on its own. Sensible names, small functions, clear signatures, structure that follows the shape of the problem. If a reader can’t tell what your code does, the answer is almost never a comment. It’s better code.

But no amount of tidying lets code express:

• Why you chose this approach when an obvious simpler one exists
• Which specific horrible edge case this workaround is defending against
• Why this apparently pointless line must not be deleted, and what broke last time somebody tried
• What the business rule actually is, and which meeting produced it
• Why the obvious solution doesn’t work here

That last one is the highest-value comment in software and almost nobody writes it. If you tried the sensible thing first and it failed, say so. You will save the next person, who is very likely to be you, from repeating the whole experiment.

A comment I’ve come to appreciate is the one that names a constraint from outside the codebase entirely. “The vendor’s API rejects batches over 500 despite the docs saying 1000.” There is no way to derive that. It is genuinely knowledge, and code cannot hold it.

When “What” Comments Earn Their Place

I’ll concede more ground here than the title suggests.

Some code is inherently hard to read and no amount of naming rescues it. Dense numerical work, bit manipulation, a regex doing something genuinely clever, an algorithm whose whole point is being non-obvious for performance reasons. Writing out what a twelve-line chunk of that does, in English, is a kindness.

Unfamiliar domain logic counts too. The code might be perfectly clear and still meaningless to anyone who doesn’t know what a chargeback reason code is.

And readers differ. A comment explaining what a particular reduce is doing is noise to one person and a lifeline to another. On a mixed-experience team I’d rather err towards the lifeline.

Where I Might Be Wrong

The whole argument assumes you’re able to write clear code and, crucially, allowed to. If you’ve inherited something genuinely awful and don’t have permission to restructure it, then “what” comments might be the only documentation that codebase will ever get. Insisting on purity there is just leaving the next person with nothing.

I’m also aware I’m generalising from mostly-readable languages. There are corners of Perl, shell, and heavily generic C++ where even experts need the English version.

The best comment explains something surprising. If a reader will think “wait, why?”, that’s where it belongs.

The Test Before You Write One

1. Ask whether you can make the code clearer instead. Usually you can. Do that
2. If you can’t, write down why, not what
3. Prefer the reason nobody could guess: the constraint, the failed attempt, the external quirk
4. If you’re explaining a workaround, name what breaks without it
5. Delete comments that narrate. They train people to skim past all comments, which is how the important ones get missed
6. When you change the code, change the comment in the same commit or delete it

That fifth point is the one I actually care about. A file full of useless comments doesn’t just waste space, it teaches everyone reading it that comments aren’t worth attention. Then the one comment that would have saved them a day goes by unread.

Until next time, happy coding!