TL;DR
A programmer argues that comments which state 'what' code is doing can be appropriate alongside explanatory 'why' comments. The post highlights practical costs of moving explanations out of the immediate code context, using examples where refactoring or commit messages make understanding harder.
What happened
The author challenges the common maxim that comments should explain only why, not what. Through short examples, they show cases where terse variable names or a repeated library call become confusing unless annotated close to the code. They argue that putting rationale solely in commit messages or tests forces readers to perform time-consuming lookups—especially when git blame becomes unreliable after refactors. The piece also examines a refactor that replaces a ten-line method with several small helper methods: although each method has a clear name, the reader must jump around to follow the control flow, which can be as disruptive as reading an inline comment. The author concludes that while clear code is preferable, there are situations where brief 'what' comments reduce context switching and lower the chance of dangerous assumptions. They warn this is not license to write poor code, and point readers toward a related essay they mostly agree with.
Why it matters
- Information placed far from the code that depends on it increases the effort to understand and maintain software.
- Missing or hard-to-find explanations can lead developers to make incorrect assumptions and introduce bugs.
- Refactoring into many small methods can improve structure but may increase context switches during debugging or code review.
- Rationale stored only in commits or tests may become hard to retrieve after code moves or formatting changes.
Key facts
- The post contests the rule 'comments should explain why, not what' and defends some uses of 'what' comments.
- An example shows that single-letter variable names (e.g., w) force readers to jump back to find meaning.
- A snippet demonstrates a duplicated library call (XYZ.clear(); XYZ.clear();) where an inline comment explains the repetition.
- The author notes that relying on commit messages to explain behavior can be cumbersome if git blame stops pointing to the original change.
- A refactor inspired by an 'Extract Method' approach replaced a 10-line function with multiple small methods, which reduced local code length but required jumping between methods to understand behavior.
- The author cautions against using this argument as an excuse for sloppy code.
- The post was originally posted on Dec 05, 2017.
What to watch next
- Whether teams revise style guides to permit concise 'what' comments in specific contexts: not confirmed in the source
- If tooling or IDE improvements reduce the cost of navigating between small extracted methods: not confirmed in the source
Quick glossary
- Code comment: Annotations in source code intended to explain intent, rationale, or details that are not obvious from the code itself.
- Commit message: A recorded note attached to a set of changes in version control describing why the change was made.
- Context switch: The cognitive or technical effort required to move from one part of code or documentation to another in order to understand or continue work.
- Refactoring: The process of restructuring existing code without changing its external behavior to improve readability or maintainability.
- git blame: A version-control tool feature that traces lines of code to the commits and authors that last modified them.
Reader FAQ
Should comments describe 'what' or 'why'?
The author argues both have their place; concise 'what' comments can be helpful when they reduce context switching and prevent incorrect assumptions.
Is it better to put explanations in commit messages?
The piece warns that storing rationale only in commits can make it hard to find later, particularly after code moves or formatting changes.
Does extracting methods always improve readability?
Not always; the author shows an example where many small methods force readers to jump around, which can hinder understanding.
Can this be used to justify writing unclear code?
No — the author explicitly asks readers not to use the argument as permission to write bad or unclear code.
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'
- What's wrong with comments that explain complex code?
- On Code Comments – Charles Chen – Medium
- Code Tells You How, Comments Tell You Why
Related posts
- How to Choose Protein Bars: Gluten-Free Picks, Whole-Food Bases, and Fiber
- Curate Your Public Reddit Profile: Make It Presentable and Privacy-Smart
- Is Wayland Ready in 2026? A Practical Test with Sway and Nvidia 8K