Why I stopped writing comments
A controversial take on code documentation and what to write instead.
I used to comment everything. // loops through users, // validates input. I thought it made me a thoughtful engineer.
Then I read code I wrote six months ago and realized the comments lied. Or were redundant. Or both.
The rule I follow now
Write code that doesn’t need comments. When you can’t, write a comment that explains why, never what.
That’s it. Two clauses.
Examples
Bad:
// increment counter
counter++;
Better — the code already says what:
counter++;
When it actually deserves a comment:
// Workaround for Safari bug #12345: requestAnimationFrame fires twice
// during page transitions. Track ticks to dedupe.
if (lastTick === now) return;
That comment carries information nothing else can.
The corollary
If you find yourself reaching for a comment to explain what a function does — extract it. Name it well. The function name becomes the comment, and it can’t drift out of sync.
Code is read more than written. Make every line carry meaning. Reserve prose for the things prose alone can express.