🧠 “A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.”
— Uncle Bob Martin
At first, I thought this quote was a bit extreme. But the more I applied it, the more I realized it's not anti-comment—it’s pro-clarity.
It’s hard to always follow this mindset though, especially when working in teams where coding habits vary and mechanisms to enforce clean code are weak or absent.
⚠️ The Problem with Comment-Heavy Code
Over time, I noticed that devs who write too many comments tend to struggle with the same patterns:
- 📏 Writing very long functions or classes
- 🔗 Coupling multiple responsibilities into single structures
- ⛔ Delaying necessary refactoring by labeling it “premature optimization”
This kind of code smells—even if it’s commented.
❌ Why Excessive Comments Are a Problem
1. 🕶️ They’re Often Ignored
Most people skim over comments. And IDEs visually de-emphasize them, making them easy to overlook.
2. 🧟♂️ They Rot Quickly
Code evolves. Comments often don’t. They become outdated and misleading, especially if they’re skipped in reviews.
3. 🧠 They Increase Cognitive Load
Reading code and reading comments to verify alignment is double the work. It slows down understanding and reduces trust in both.
Every codebase I’ve seen overloaded with comments had all three of these issues.
✅ How to Write Code That Explains Itself
Instead of writing explanations about code, write code that needs no explanation.
Here’s how:
- 🧩 Design for readability
- 🏷️ Use descriptive, intention-revealing names
- ✂️ Keep functions and classes small
- 🧱 Compose, don’t couple
- 🧪 Write testable, self-validating code
Good code is the best documentation. Let the structure speak for itself.
💬 When Comments Are Worth It
Not all comments are bad.
Here’s when they add value:
- 🧾 Explaining business rules or regulatory edge cases
- 🕸️ Highlighting non-obvious decisions
- 🔗 Linking to external specs or documentation
These comments are rare—and they should be. Think of them as signposts, not safety nets.
🧭 Structure Matters More Than You Think
Even the order of code impacts readability.
I like to write code like a story—top to bottom, like a book. This makes navigation easier for future readers and for reviewers.
Yes, IDEs allow fast jumping. But on platforms like GitHub, code review still happens linearly. Keeping related logic close together and avoiding jumping around helps a lot.
🔚 Final Thoughts
Too many comments usually point to code that isn’t clear on its own.
Instead of relying on comments to explain your work, strive to write:
- Clean,
- Concise,
- Testable,
- Readable code.
When you do need a comment, make it count.
🙏 Thanks for reading!
If this resonated with you or you’ve seen (or written) comment-heavy codebases, share your thoughts below. I’d love to hear how your team balances readability and documentation.
Top comments (0)