Let me paint you a picture.
It’s 11pm. You’ve just inherited a 3,000-line file from a developer who left the company 18 months ago. You scroll through it, desperately looking for anything that tells you what this function actually does. And then you find it — a comment. A glorious, illuminating comment. You lean forward. Your eyes widen. You read:
<pre><code>// do the thing
function doTheThing() {
</code></pre>
Incredible. Truly. Career-defining documentation right there.
<hr>
Here’s my take after years of reading other people’s crimes against readability: most code comments are a coping mechanism for writing bad code.
I don’t mean that as an insult. I mean it literally. When you feel the urge to write a comment that explains what your code does, that urge is your brain politely telling you: “hey mate, this code isn’t clear enough.” The comment is the symptom. The variable name is the disease.
The “what vs why” test
This is the only framework you need. Ask yourself: does this comment explain what the code does, or why it does it?
WHAT comments = almost always removable:
<pre><code>// loop through users
users.forEach(user =&gt; {

// check if age is over 18
if (user.age &gt;= 18) {

// return true
return true;
</code></pre>
These are noise. If you need to explain what <code>users.forEach</code> does, we have bigger problems.
WHY comments = genuinely valuable:
<pre><code>// Using XOR swap here instead of a temp variable because this runs
// 40 million times per second in the render loop and profiling showed
// the allocation was causing GC pressure. See perf ticket #4421.

// Intentionally NOT using the user&#x27;s locale here — legal confirmed
// that displaying localised pricing violates the EU agreement until
// Q3. Remove this after the contract renegotiation.

// This looks wrong but it&#x27;s correct. The API returns timestamps
// in PST despite the docs saying UTC. Filed bug with vendor 6mo ago,
// no fix yet. Do not &quot;fix&quot; this.
</code></pre>
See the difference? The second set of comments contain institutional knowledge. Information that lives nowhere else. If you delete them, you lose something real. The first set contain information that’s already in the code itself.
<hr>
“But what about beginners reading my code?”
This is the most common pushback I get, and I understand it. But here’s the thing: if a junior dev can’t understand <code>if (user.isAdmin)</code>, the solution is not <code>// check if user is admin</code>. The solution is mentorship, code review, and documentation at the module/API level — not inline narration of your if-statements.
Code comments are not a substitute for readable code. They’re a supplement for the cases where readable code genuinely isn’t enough.
<hr>
The rot problem nobody talks about
Here’s what really kills me about over-commented code: comments lie.
Code cannot lie. If your code does X, it does X. But a comment that says “this returns a string” can sit there, perfectly confident and completely wrong, for three years after someone changed it to return an object. Comments don’t get updated in code review. They don’t get flagged by linters. They just quietly go stale while the actual code moves on without them.
I’ve seen more bugs introduced by developers trusting an outdated comment than by developers reading the actual code. There’s a special kind of debugging hell where the code and the comment contradict each other and you have to figure out which one is lying.
Spoiler: it’s always the comment.
<hr>
What actually makes code readable (without comments)
<ul>
<li>Name variables like they’re going to be read by someone who has never met you (because they will be)</li>
<li>Keep functions small enough that the function name fully describes what they do</li>
<li>Use positive conditions: <code>isEligible</code> beats <code>!isNotEligible</code> every time</li>
<li>Extract magic numbers: <code>const MAXRETRYATTEMPTS = 3</code> instead of just <code>3</code> floating in the void</li>
<li>Structure your code so it reads top-to-bottom like a newspaper, not like a treasure hunt</li>
</ul>
<hr>
The comments worth keeping (my personal shortlist)
<ol>
<li>Why you picked a weird algorithm — if you’re doing something non-obvious for performance, document the profiling that justified it</li>
<li>Why you’re NOT doing the obvious thing — “we tried X, it caused Y, do not revert this” is priceless</li>
<li>External references — ticket numbers, spec URLs, vendor bug links</li>
<li>Intentional weirdness — <code>// eslint-disable-next-line</code> with an actual explanation of why</li>
<li>TODO/FIXME with names and dates — <code>// TODO(shane): remove after migration, see ticket #892</code> not just <code>// TODO: fix this</code></li>
</ol>
<hr>
Look, I’m not saying delete every comment in your codebase today. I’m saying the next time you write a comment, ask: could I make this unnecessary by writing better code instead?
Nine times out of ten, the answer is yes.
The tenth time — write the best comment of your life and make it count.
Drop your most unhinged comment horror story below. I’ll start: I once found <code>// I have no idea what this does but removing it breaks everything</code> in production code at a Series B startup. The function had been there for four years. Nobody touched it. It remains today.
#webdev #programming #javascript #cleancode #discuss
<pre><code>
</code></pre>

Shane

Most code comments are a coping mechanism for unclear code. The key test is whether a comment explains 'what' the code does (almost always removable) or 'why' it does it (genuinely valuable). 'What' comments are noise that duplicates readable code, while 'why' comments preserve institutional knowledge that exists nowhere else. Comments also rot — they go stale silently while code evolves, causing more bugs than they prevent. Better alternatives include descriptive variable names, small focused functions, positive conditions, named constants, and logical top-to-bottom structure. The comments worth keeping are those explaining non-obvious algorithm choices, why the obvious approach was rejected, external references, intentional workarounds, and dated TODO/FIXME entries.

Stop writing comments in your code. Write code that doesn't need them.