Comments Should Explain Why, Not What

The Claim

Comments that explain what code does are useless or worse than useless. Comments should only explain why-the context, intent, and reasoning that the code itself can’t express.

Why I Think This

// Increment counter by one
counter += 1;

This comment tells me nothing the code doesn’t already say. It’s noise. Worse, it’s noise that might become wrong when someone changes the code but forgets the comment.

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

Now I understand something I couldn’t learn from the code alone. The comment answers “why is this weird?” which is exactly when I need context.

The best code is self-documenting for the “what.” Good variable names, clear function signatures, logical structure-these tell you what’s happening. But code can’t tell you:

• Why you chose this approach over alternatives
• What weird edge case necessitated this workaround
• Why this seemingly unnecessary code exists (maybe a bug fix)
• What the business context is for this logic
• Why the obvious solution won’t work

Those are the comments worth writing.

The Counterargument

Sometimes code is inherently complex, and explaining what it does is genuinely helpful. Dense algorithms, unfamiliar domain logic, or performance-optimised code might need “what” comments for anyone who didn’t write it.

And not everyone reading code has the same skill level. A comment explaining what reduce does might be noise to a senior engineer but helpful to a junior.

Where I Might Be Wrong

I’m assuming everyone writes readable code. If the codebase is messy (and you can’t clean it up), “what” comments might be the only documentation anyone will ever have.

Also, some languages and paradigms are inherently harder to read. Perl one-liners, regex, bit manipulation-these might legitimately need “what” comments because even experts struggle to parse them.

The Takeaway

Before writing a comment, ask: “Can I make the code itself clearer instead?” If yes, do that. If no, write a comment explaining why this code exists, not what it does.

The best comment is the one that explains something surprising. If the reader will think “wait, why?"-that’s where your comment belongs.

I delete “what” comments in code review. They’re not just useless-they train people to skim past all comments, including the important ones.