TL;DR
A blog post challenges the common rule that comments should only explain why, arguing there are situations where comments describing what is happening reduce costly context switches. The author uses short-variable examples, a duplicated-clear call, and a refactor-by-extraction example to show when 'what' comments can aid comprehension and debugging.
What happened
A programming essay contested the oft-repeated guideline that comments must explain only why, not what. The writer acknowledges that clear naming and structure are preferable, but presents cases where an explanatory 'what' comment is useful. One example contrasts terse single-letter variables with descriptive names, noting that readers encountering the variable later may misinterpret its meaning and introduce bugs. Another example shows a duplicated library call and argues that burying the reason in a commit message makes it hard to discover later; an inline comment beside the call preserves the rationale at the point of use. The post also examines a refactor that extracts many small methods: while the code becomes ‘cleaner’, following behavior may require jumping across methods, creating its own context-switch cost. The author concludes that comments which state what is happening can be justified when they reduce cognitive overhead, while warning not to use that as an excuse for poor code.
Why it matters
- Inline explanations can prevent mistaken assumptions that lead to bugs, especially when reading code out of context.
- Keeping rationale next to the code avoids digging through version history or commits, which is time-consuming and fragile.
- Excessive fragmentation into tiny methods can force developers to jump around, reducing the practical readability gains of refactoring.
- A pragmatic balance between descriptive code and targeted comments can improve debugging and maintenance efficiency.
Key facts
- The author disputes the strict rule that comments should only explain why and never what.
- Short or ambiguous variable names can force readers to search elsewhere to learn their meaning.
- Rationale stored only in commit messages can be hard to find later if code is reformatted or moved.
- An example used: repeating a library clear() call with an inline comment explaining the repetition.
- A refactor example (from Bob Martin’s 'Extract Till You Drop') replaces a ten-line method with many small helpers, which may increase context switching.
- The author proposes that, in some cases, a concise 'what' comment inside a method is preferable to spreading logic across many methods.
- The writer cautions against using this argument to justify writing unclear or sloppy code.
- The post references another essay ('The Lurn') and signals agreement on some points and disagreement on others; specifics about that disagreement are limited in the source.
What to watch next
- Whether teams revise their commenting guidelines to allow more 'what' comments when they reduce context switching — not confirmed in the source
- How code-review practices evolve to balance descriptive naming, extraction, and inline comments — not confirmed in the source
- Whether tool support (editors, IDEs) will change to make navigating extracted methods less costly — not confirmed in the source
Quick glossary
- Inline comment: A short explanatory note placed in the source code near the code it describes, intended to clarify intent or behavior.
- Commit message: A brief description attached to a set of code changes in a version control system explaining what changed and why.
- Context switch: The mental overhead of stopping work in one place to look up information elsewhere, such as jumping between methods or files while reading code.
- Refactoring: The process of restructuring existing code without changing its external behavior to improve readability, structure, or maintainability.
- git blame: A version-control tool feature that identifies the commit and author responsible for a given line of code, often used to trace changes.
Reader FAQ
Should comments ever explain what the code does?
According to the source essay, yes—when such comments reduce context switching and make the code easier to understand in place.
Are comments a substitute for clear code?
No. The post warns that comments are not an excuse for unclear naming or sloppy structure, though they can be helpful in some cases.
Should reasons for odd code be put only in commit messages?
The author argues that putting rationale solely in commits is problematic because it makes the reasoning harder to find; inline comments can be more practical.
Is extracting small methods always better for readability?
The source contends this is not always true; many tiny methods can increase the reader's need to hop across the codebase, creating additional context switches.
MAYBE COMMENTS SHOULD EXPLAIN 'WHAT' Contact via Email Open Github account in new tab Posted on Dec 05, 2017 People say “Comments should explain why, not what.” I feel like…
Sources
- Maybe comments should explain 'what' (2017)
- What's wrong with comments that explain complex code?
- The hopeful future demise of Code Commenting
- Code Tells You How, Comments Tell You Why
Related posts
- How a Christmas beach moment with my partner changed Google Photos use
- Was It Really a Billion Dollar Mistake? Reassessing Null Pointer Costs and Trade-offs
- FreeBSD Home NAS, Part 3: WireGuard VPN, Linux Peers & Routing