Español

Comment The Why, Never The What

Delete ninety percent of your comments. Keep one kind. Most comments in a typical codebase restate what the line below already says — and a comment that restates the code rots the moment that line changes. The one kind worth keeping records something the code cannot say: why it exists.

The comment that lies

PEP 8 uses the canonical example as its own "don't do this":

x = x + 1                 # Increment x

That comment adds zero information today, and worse: it's a lie waiting to happen. Change the line to x = x + step and the comment is now wrong — and nobody updates comments the way they update code. PEP 8's counter-example is the fix: x = x + 1 # Compensate for border. Same line, but now the comment carries context the code can't express.

Stack Overflow's engineering blog puts it as rule number one for code comments: comments should not duplicate the code. Redundant comments clutter the file, cost maintenance time, and drift out of date. Refactoring.guru goes further and lists explanatory comments as a code smell in the "Dispensables" category — usually a sign the code itself needs renaming or extracting, not annotating.

What vs. why, on one line

# WHAT (delete this — the code already says it):
window.clear()  # clear the window

# WHY (keep this — the code can't say it):
window.clear()  # reset the counter on a sliding window
                # to stop burst attacks at the window edge

The first comment repeats the method name. The second records a decision: someone chose a sliding window over a fixed one, for a specific threat model. Refactor the implementation — rename the method, swap the data structure — and the why-comment stays true, because intent doesn't change when the code does.

Rules of thumb

If you struggle to write a clear comment, that's often a signal the code needs work — extract a well-named function instead of annotating a confusing block.

Why-comments are AI-assistant fuel

Here's the modern payoff. AI coding assistants read your comments as part of their context — and they weigh them as statements of intent. A what-comment gives the model nothing it didn't already parse from the code. A why-comment does two things:

• It stops re-litigation. "Sliding window to stop burst attacks at the window edge" tells the assistant this was a deliberate choice. Without it, an agent asked to "clean up" the rate limiter may helpfully simplify it to a fixed window — undoing a decision nobody wrote down.
• It transfers constraints. "Don't parallelize — the API rate-limits per connection" keeps both your teammates and your coding agent from making the same tempting mistake.

The cheapest way to align an AI assistant with your codebase's decisions is to have written those decisions down where they apply — inline, as why-comments.

Power-user moves

• Comment the rejected alternative. The highest-value comment is often "we tried X; it failed because Y." It saves the next person (or agent) a whole detour.
• Link, don't paraphrase. Copied a snippet or worked around a library bug? Put the URL in the comment. A source beats a summary and can be re-checked later.
• Audit with a grep. Scan for comments whose words appear in the line below them (increment, set, return, loop over) — those are what-comments and near-free deletions in review.
• Escalate big whys to ADRs. When the "why" spans a module rather than a line, it belongs in an architecture decision record — same principle, bigger scope.

Resources

• PEP 8 — Inline comments (the "Increment x" example)
• Best practices for writing code comments — Stack Overflow Blog
• Code Tells You How, Comments Tell You Why — Coding Horror
• Comments as a code smell — Refactoring.Guru