Why comments aren't necessary Aug 11
Many years ago, I learned from a developer I deeply admired that “comments are bad”. At the time, this seemed counterintuitive - weren’t comments supposed to make code more understandable? But because I respected his expertise, I pressed him to explain. His reasoning was straightforward:
You don’t need comments if your code is self-explanatory.
When you think about it, this makes a lot of sense.
If you’re adding a comment to explain what the code does, you’re essentially admitting that the code itself isn’t clear enough. Comments become a band-aid for poor naming, confusing structure, or overly compact logic.
Instead of writing a comment, take a moment to ask yourself: Can I rename this variable to clearly convey its meaning? Can I extract this logic into a small, well-named function to make the intent obvious?
Example:
// only people above 18 are eligible to vote
if (age >= 18) this.vote()
This works, but the comment merely restates what the code is already doing. If the reader can’t understand the code, it’s because it isn’t written clearly enough.
Refactor it like this:
const eligibleToVote = age >= 18
if (eligibleToVote) this.vote()
Now the code speaks for itself. No extra explanation is required.
Why fewer comments = better code
Comments can become out of sync. You change the code but forget to update the comment, and suddenly it misrepresents the code. Worse, people tend to trust comments without questioning them. Self-documenting code avoids this issue - what you see is what’s actually happening.
By forcing yourself to make the code readable on its own, you naturally:
- Choose better names
- Write smaller, more focused functions
- Avoid cramming too much logic into one place
The result is code that’s easier to read, easier to change, and far less likely to confuse the next person who works on it (including you, three months from now).
So, the next time you’re about to write a comment, pause for a moment and ask yourself, “Could I make this so clear that no comment is needed?” Most of the time, the answer will be yes, and your code will benefit from it.