Code comments quote

“Code comments are for those who either cannot read the code or whose code cannot be read.”

That observation cuts in two directions, and that’s what makes it worth sitting with.

The first direction is generous: comments exist to help readers who aren’t yet fluent in the codebase, the language idioms, or the domain logic embedded in the implementation. There’s no shame in that. We all move through phases of fluency, and a well-placed comment can shorten the ramp significantly.

The second direction is harder: if your code consistently requires explanation to be understood, the problem isn’t missing comments. The problem is the code. Comments that narrate what the code does—rather than why a non-obvious decision was made—are often a symptom of complexity that should have been eliminated, not annotated. Every time you write // increment counter above i++, you’ve added noise without adding clarity.

The ideal, of course, is code that reads as clearly as well-written prose. Meaningful names, small functions, obvious structure. Code that reveals intent without requiring translation. In that state, comments become rare—reserved for the genuinely surprising: the business rule that defies intuition, the algorithm that optimizes at the expense of readability, the workaround for a known platform bug.

There’s a fair counterpoint: even well-written code benefits from comments after time away from it. Memory is short. What feels obvious when you’re writing it feels foreign six months later. Comments that capture the reasoning—not the mechanics—serve future you as much as they serve anyone else.

So the real distinction isn’t “commented versus uncommented.” It’s between comments that explain intent and comments that apologize for complexity. Write code that needs fewer of the latter.