Code Comments: Documentation or Admitting Your Code Sucks?

Every code comment is a confession. It’s you admitting that you couldn’t write code clear enough to stand on its own. It’s a digital apology note saying “I know this looks insane, but here’s what I was trying to do.”

The programming world has convinced itself that comments are documentation. They’re not documentation—they’re band-aids for bad code.

Real documentation lives in README files, API specs, and architectural decisions. Comments are what you write when you’ve given up on making your code readable and decided to explain your mess instead of cleaning it up.

Here’s the truth that makes code reviewers uncomfortable: If your code needs comments to be understood, you wrote bad code.

Walk through any legacy codebase and you’ll find comments explaining what the code does instead of why it exists. “Loop through users and check permissions.” Thanks, Captain Obvious. I can see the for loop. What I can’t see is why you’re checking permissions in a utility function instead of the authentication middleware where it belongs.

The worst offenders are the lying comments. Code evolves, but comments fossilize. They become archaeological artifacts from a different era, misleading developers about what the code actually does. That comment saying “temporary workaround” above three-year-old production code isn’t documentation—it’s historical fiction.

Then there are the insult-your-intelligence comments: i++; // increment i. Really? The increment operator has been part of programming since the 1960s. If you need to explain what i++ does, your readers have bigger problems than understanding your code.

The commenting culture has created developers who think clarity is optional. They write cryptic variable names (data, flag, temp), nest ternary operators like Russian dolls, and create incomprehensible function signatures, then slap comments over the wounds like band-aids.

Instead of naming a variable isUserEligibleForDiscount, they call it flag and add a comment explaining what the flag represents. Instead of extracting magic numbers into named constants, they add inline comments explaining what 86400000 means.

Comments become crutches that enable lazy thinking. Instead of refactoring a 200-line function into smaller, focused functions with descriptive names, developers add section comments and call it “well-documented.” Instead of writing self-explanatory code, they write cryptic code with helpful explanations.

The most damning evidence? Every experienced developer ignores comments when debugging. We instinctively know that comments lie, but code doesn’t. The compiler executes your logic, not your explanations. When production breaks at 2 AM, you trust what’s actually running, not the cheerful comment from 2019 promising “this should never fail.”

Well-written code doesn’t need comments. When you see if (customer.qualifiesForFreeShipping()), you don’t need a comment explaining that this checks shipping eligibility. The method name is the documentation. The code explains itself.

We’ve created a culture where writing bad code and explaining it is somehow more professional than writing good code that needs no explanation. Code review checklists ask “is this well-commented?” when they should ask “is this well-written?”

Your code should tell a story so clear that interrupting it with comments would be redundant. Every comment is you admitting you couldn’t tell that story well enough the first time.

The best code doesn’t need comments because it speaks for itself. Everything else is just apologizing for bad writing.