Steve McConnell nailed it back in Code Complete:
“Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer.”
Everyone loves quoting the first half. Code review debates, Twitter threads, team Slack wars—someone inevitably drops “good code is its own best documentation” like it ends the argument. But almost nobody remembers (or wants to remember) the second half: the part where you’re supposed to actually refactor instead of slapping a comment on top.
From personal experience: I’ve lost count of how many times I’ve weaponized that quote when defending my own code (“see? no comment needed!”), and how many times I’ve cursed under my breath while trying to decipher someone else’s legendary, comment-free masterpiece.
The harsh truth most of us don’t want to admit: very few programmers (myself included) are consistently skilled enough to make code so self-explanatory that comments become truly redundant. We’ve all inherited code from “rockstar” engineers—the ones whose exploits are legendary in school projects, open-source repos, or company folklore. You finally get handed their codebase and… oof. Thousands of lines, zero comments. Magic public library calls with zero docs, or docs so vague they’re basically “it works, trust me.” You step on the same undocumented landmine three times, swear quietly, and the next time someone gushes about that dev’s brilliance, you just fake a smile and think: “Sure, buddy. Sure.”
The real debate isn’t “can the best code skip comments entirely?” (maybe a handful of 10x wizards can). The practical question for teams is: should we ever encourage the idea that “comments are optional”?
If you broadcast “comments can be omitted if the code is good enough,” what most people hear is “yay, I never have to write comments again.” Especially dangerous for juniors fresh out of college who’ve never even heard the word “documentation” outside a syllabus footnote. Tell them comments are skippable, and their code will be nowhere near self-documenting—it’ll just be undocumented garbage.
In a company setting, comments aren’t just nice-to-have; they’re a team survival mechanism. They affect every collaborator today, every future maintainer tomorrow, and yes, your own professional reputation when someone else has to read your six-month-old mess. So my personal stance hasn’t budged: comments are mandatory. The more thorough the better. Overdo it? Fine—better safe than sorry.
For solo work or personal projects, the “good code = best docs” mantra sounds great… until you open your own code from half a year ago with zero comments and think: “Who the hell wrote this garbage?!”
Moral of the story: Aim for crystal-clear code that minimizes the need for comments. But don’t use that ideal as an excuse to skip them. Write the damn comments. Your future self (and the poor soul who inherits your repo) will thank you.