You’ve felt it. That sinking feeling when you open a file, see perfectly formatted, “clean” code — and have absolutely no idea why it does what it does. You’ve been told that comments are a crutch. That code should be self-documenting. That if you need a comment, you’ve failed.
Bullshit.
A comment is not a confession of failure. It’s a gift to your future self. And the people who tell you otherwise are peddling a dangerous dogma that’s quietly rotting your codebase from the inside.
Let me show you what I mean. Last week, I inherited a function that calculated a discount. Fifteen lines, perfectly named variables, no comments. But why 15%? Was it a regulatory requirement? A competitor benchmark? A mistake from a Slack thread in 2019? I had to dig through three different channels, a Jira ticket, and a Loom video to find out. The code was “clean.” The knowledge was gone.
Here’s the truth that the clean code evangelists won’t tell you: Code can only express the ‘how’. It can never express the ‘why’. The ‘why’ lives in business meetings, whiteboard sessions, late-night emails, and the context of the moment. That context is what comments preserve. Without them, your codebase is a beautiful, gleaming graveyard of decisions you no longer understand.
I’m taking a side, and it’s not the popular one. The obsession with self-documenting code is creating a generation of developers who can write elegant loops but can’t answer the simplest question: “Why does this exist?” Clean code without comments is like a beautiful map with no legend.
And here’s the real twist: the pursuit of “clean code” as a substitute for comments is actually accumulating technical debt. The debt isn’t bad formatting or global variables. It’s missing context. It’s the time you’ll spend reverse-engineering intent. It’s the bug you’ll introduce because you assumed a different reason.
So what should you do? Not every line needs a comment. But every decision that isn’t obvious from the code itself — every business rule, every workaround, every historical constraint — deserves a sentence that explains why this code exists at all. That’s not a crutch. That’s responsibility.
Next time a code review tells you to remove a comment, ask them: “What business reason made this the right decision?” If they can’t answer, the comment stays. Because code without context is just noise. And noise is the enemy of maintainability.
Your comments are not the enemy. The real enemy is a culture that values purity over clarity. Write the comment. Save your future self.
FAQ
Q: Aren't comments just maintenance overhead that goes out of date?
A: Outdated comments are a problem, but they're a symptom of a process failure, not a reason to ban comments. The solution is to treat comments as part of the codebase — review them, update them, and delete them when the code changes. The alternative (no comments) means you lose all context. I'd rather fix a stale comment than reconstruct a forgotten decision.
Q: So should I write a comment for every line of code?
A: No. Comment the 'why', not the 'how'. If the code is self-explanatory (e.g., a simple calculation), don't comment. But when the reason is non-obvious — a business rule, a workaround for a third-party bug, a historical constraint — a single sentence can save hours of digging. The rule: the comment should explain something the code cannot.
Q: Isn't self-documenting code the ideal? Why not just write better code?
A: Self-documenting code is a noble goal, but it's a myth in practice. Code can describe the mechanics (the 'what'), but it cannot express business intent, external dependencies, or the context of a decision. A function named 'applyDiscount' tells you nothing about why the discount is 15%. Better naming helps, but it can't replace the sentence: 'This discount matches the Q3 regulatory cap for region EU.' Comments bridge that gap.