Ask a senior developer why they write code comments and they’ll probably say something about helping the team. It sounds collaborative, even noble. But watch what they actually write, and a different pattern emerges. The best comments aren’t explanations for strangers. They’re messages written to a specific, imagined reader: the author, six months from now, under pressure, with no memory of why any of this made sense.
This kind of counterintuitive behavior shows up constantly in tech. The habits that look selfless on the surface often have a sharper, more personal logic underneath.
The Memory Problem Nobody Talks About
Here’s something cognitive science has known for decades that the software industry largely ignores: working memory is not a filing cabinet. It’s a whiteboard that gets erased constantly. When a developer is deep inside a complex function, they hold an elaborate mental model in their head, the constraints, the edge cases, the three other systems this touches, the reason the obvious solution doesn’t work here. That model can take 20 to 30 minutes to rebuild after any interruption.
The problem is that once the code is written, that mental model evaporates. Not gradually. Almost entirely. Studies on programmer cognition suggest that developers forget roughly 60 percent of the reasoning behind a decision within a few days of making it. The code persists. The context doesn’t.
A comment written in that moment of maximum understanding isn’t documentation. It’s a cognitive artifact, a compressed snapshot of a mental state that will never naturally recur.
Why “What” Comments Are Almost Worthless
Most junior developers, when they comment at all, describe what the code does. This is the least useful thing you can write.
# Loop through users
for user in users:
process(user)
Anyone who can read Python already knows that’s a loop through users. The comment adds zero information. Compare that to:
# Users are processed in insertion order here because the
# downstream billing system expects charges to appear
# chronologically. Sorting by ID breaks reconciliation.
for user in users:
process(user)
The second comment doesn’t describe the code. It explains the invisible constraint the code is satisfying. It captures a piece of reasoning that required three hours of debugging and a call with the billing team to uncover. Without that comment, the next developer (likely the original author) will look at the unsorted loop, assume it’s sloppy, sort it by ID for cleanliness, and break reconciliation.
This is the comment that saves a production incident. And it was written entirely for selfish reasons.
The Expertise Paradox
Here’s where it gets interesting. Novice developers tend to write more comments than experts, but worse ones. They annotate the obvious because they’re not sure what’s obvious yet. Expert developers write fewer comments, but they’re dramatically more valuable, because they’ve learned to recognize which knowledge is genuinely non-recoverable.
An expert knows the difference between logic that’s self-explanatory from the code structure and reasoning that exists entirely outside the codebase, in a Slack thread from eight months ago, a quirk in a third-party API, a constraint imposed by a regulation nobody remembers signing off on.
Tech companies build entire strategies around this kind of invisible knowledge. The reasoning that isn’t written down doesn’t just get forgotten. It becomes a liability.
The expert developer’s comment is essentially a message in a bottle. They’re not writing for an abstract future reader. They’re writing for the specific future moment when someone (probably them) is confused, tired, and under pressure, and needs to understand not what the code does but why it was written this way and not some other way.
The “Why Not” Convention
The most underused commenting pattern in professional codebases is the “why not” comment. It documents the approaches that were considered and rejected.
// Not using a Set here even though it would be faster.
// The order of insertion matters for the UI diff algorithm.
// See issue #4821 for the three-hour discussion about this.
const seen = [];
This pattern does something subtle but powerful. It preemptively answers the question every future reader will ask: “Why didn’t they just do the obvious thing?” Without it, the next developer sees what looks like a performance oversight, “fixes” it, and reintroduces a bug that was already debugged.
Software teams that adopt this convention report dramatic reductions in regression bugs, those maddening cases where a problem was already solved and then accidentally unsolved. It’s not documentation for documentation’s sake. It’s institutional memory compressed into a single line.
This connects to something broader about how the best technical teams operate. Top performers consistently find ways to schedule and contain their cognitive overhead rather than treating mental load as an inevitable tax.
What This Means for Code Reviews
If you accept that the best comments are written for the author’s future self rather than the team, it changes how you think about code reviews.
A reviewer who asks “did you document this for your teammates?” is asking the wrong question. A better question is: “Six months from now, when you’ve forgotten everything about why you wrote this, will you be able to reconstruct the decision quickly?”
That reframe also produces better comments naturally. When you write for an abstract team, you tend toward formality and comprehensiveness, which produces long, stiff documentation that nobody reads. When you write for your own confused future self, you tend toward honesty and specificity. You write what you’d actually want to know. You include the edge case that nearly broke everything. You mention the three other files this touches.
Those comments are useful to teammates precisely because they’re useful to you. The selfishness is the point.
The Bigger Pattern
The habit of writing comments for yourself is really a habit of treating your future self as a distinct person, someone who will lack context, be under pressure, and need clear information quickly. That’s a surprisingly rare skill, and it shows up in other high-performance behaviors too.
Digital minimalists who deliberately manage their cognitive environment are doing something structurally similar: designing their present behavior around the known limitations of future attention.
The developers who write the best comments aren’t being considerate. They’re being precise about a real problem, the gap between knowing a system deeply and being able to reconstruct that knowledge later. The team benefits as a side effect. But the comment exists because the author was smart enough to distrust their own memory.
That’s not a quirk. That’s engineering.
