January 4, 2026
What vs Why Smackdown
Maybe Comments _Should_ Explain 'What'
Readers revolt: Just say what it does so we can fix stuff
TLDR: A bold post says comments should sometimes explain what the code does, not just why, to save readers time. Most commenters cheered and dunked on hyper-fragmented styles, while a few warned not to excuse messy writing—because quick, clear notes can stop costly mistakes in real projects.
An author lit a match under a coding rule—comments should explain why, not what—and the internet showed up with popcorn. The post argues that brief notes telling readers what tricky lines are doing can prevent wild goose chases and bad guesses. Commenters pounced, with many roasting the old 'tiny methods everywhere' style made famous by software guru Uncle Bob. One user grumbled about endless 'go to definition' gymnastics; another declared that readability is king and splitting one idea into six jumps is method hopscotch. Jokes flew about Where’s Waldo debugging and getting cardio from the jump-to-definition key.
Others cautioned: don’t use comments as a hall pass for messy code. Still, they said, a quick what-comment beats digging through commit history (the record of changes) or playing detective when a duplicated line exists for a reason. A widely shared link, Don’t refactor like Uncle Bob, set the tone. One developer admitted they add explanations when an algorithm gets brain-bendy. Another insisted the whole point of comments is understanding—sometimes that’s 'why', sometimes it’s 'what'. The minority view: write clearer names and tests and you won’t need extra prose. The vibe: fewer treasure hunts, more helpful notes, right where the confusion starts.
Key Points
- •The article contends comments should sometimes explain both “what” and “why,” not strictly only “why.”
- •Descriptive code is preferred for conveying “what,” but comments can still be necessary when code remains non-obvious.
- •Storing rationale in commit messages or tests can force context switching and make understanding changes harder, especially after refactors.
- •Keeping explanations close to the code (names or comments) reduces cognitive load and prevents risky assumptions.
- •Aggressive refactoring into many small methods (e.g., “Extract Till You Drop”) may increase navigation and hinder comprehension during debugging.