🔇Over-commenting is a code-smell: How to decide when comments are worth it
🎯 Featuring insights from 10 software engineers. Learn when to use comments to clarify, when they harm, and how to write clean, self-explanatory code with minimal clutter.
I’m doing code reviews, and there’s a line of code I don’t understand. Should I ask for an explanation in the PR, for a comment in the code, or for a refactor in the next revision?
This is a long-running debate in software engineering. Some say they’re essential for clarity; others argue they’re unnecessary clutter.
Done right, comments clarify.
Done wrong, they confuse.
Let’s explore when to comment and when to let the code speak for itself.
⭐ In this article you’ll learn
When comments improve code and when they harm it.
Writing self-explanatory code with minimal comments.
Striking the balance between comments and clean code.
The risks of over-commenting and poor reliance on them.
✅ When Comments Are Beneficial
1️⃣ Explaining complex algorithms
Sometimes the problem we are solving is complex by nature. Comments can help to understand it.
2️⃣ Providing context for non-obvious solutions
Sometimes you make a temporary workaround because of some dependency. Or you are missing work to implement in a future task. A comment helps understand those details not obvious
3️⃣ Clarifying WHY behind an implementation
Redundant comments are just places to collect lies and misinformation - Robert C. Martin
Explain why, not what. Let the code handle the obvious and use comments to justify decisions
For example, the code for a sorting algorithm should be clear to understand what it does. But it’s not clear why we implemented it instead of reusing the default language’s sort() method
❌ When comments create more harm than good
1️⃣ Stating the obvious
Your developers are not learning programming for the first time. Programming languages syntax is already plain english, no need to write it again
Trust your developers
// Iterate the users array <- **❌ BAD COMMENT**
for (let i = 0; i < users.length; i++) {
console.log(users[i]);
}
2️⃣ Outdated comments
A misleading comment is worse than none. If comments aren’t updated with code changes, they confuse future developers
This happened to me recently. A client’s code had a comment claiming “We use ID_1 instead of ID_2 because old records in <MY SERVICE> database are corrupted”.
Fast forward multiple years to the present, neither the client or my team had any context about corrupted old records
More importantly… DO WE HAVE CORRUPTED DATA IN PRODUCTION AND NOBODY KNOWS ABOUT IT?
Comments like this without context only create insecurity when doing code changes. It’s like a code without Unit Tests.
They come from people who didn’t validate what they wrote in the comment and provided no references to a conversation about this.
3️⃣ Compensating for bad code
If you need comments to explain messy code, refactor the code instead.
Favor readable, intuitive code instead of verbose explanations.
Good code rarely needs an explanation beyond some references for context.
Over-commenting is a code-smell. Period.
⚖️ Finding the balance: Comments best practices
1️⃣ Write Self-Documenting Code
Modularize your code and use descriptive names for classes, functions, and variables.
A good code structure brings more clarity than any comment.
2️⃣ Use Comments judiciously
Ask yourself: Can I make this understandable by changing the code instead of writing a comment?
3️⃣ Regularly Update Comments
During refactors, verify that the comments match the current state. It’s your responsibility in each commit not to leave comments outdated.
Treat outdated comments as bugs.
4️⃣ Automate Documentation
Use tools like Javadoc or Swagger for API-level explanations. These tools allow developers to provide context and explanations in a structured way, without cluttering the codebase.
5️⃣ Minimum viable comment
Don’t write a novel in your comments. Write the sharpest and most concise sentences you have ever written.
If you struggle with that, write your lengthy comment and ask ChatGPT to make it shorter. We have no excuses nowadays.
🎯 Conclusion
Even for those who pushed back against the original post on LinkedIn, I see a common agreement: Whenever possible, code should speak for itself.
Of course, some complex logic or important decisions can’t explain themselves. A comment would help.
Make your comments concise and precise. Strive for code that reads like prose, with comments that enhance understanding when needed.
Prasad Rao, Principal Solutions Architect at AWS and author of Big Tech Careers newsletter is conducting a 9-day workshop, “Big Tech Interview Preparation Workshop for Tech ICs and Leaders” to help you land your dream MAANG+ job in 2025.
There’s a 25% discount until Sunday: https://maven.com/s/course/344c13503e (disclaimer: affiliate link where I’d get 10% of it)
🎁 Bonus Tip
Most comments can be replaced by creating a variable, function, or separate class to encapsulate some data and logic
🗞️ Other articles people like
👏 Weekly applause
- . More than technical skills, you should first learn about managing time and setting boundaries. This is the way engineers can grow without burning out.
28 Year Old Staff Engineer @ Google by
. I particularly liked how he would have focused on going slower to reduce the impostor syndrome. At the same time, I don’t think he’d have reduced it when getting promoted, rather he’d have taken it easier until the next impostor syndrome period.Turn Side Projects Into Wins At Work by
. Simple but effective. Most times we see an opportunity but we don’t think that reaping an impact from it is just 2 steps away. I like how simple Sidwyn put the steps!
I prefer to add comments when I have to include the "WHY" this was done the way it is.
For example, we had a case where we couldn't migrate to the latest version of MySQL. Because of that, we had to do a tweak in the code, so then I added a comment and a link to the documentation describing why we had to do it that way.
Recently renamed my regex to be meaningful and that was super cool 😎
For example:
```js
let startsWithBAndHasTwoDigitsCommaSeparated = new RegExp(/^B\d{2}(,B\d{2})*$/gm);
```