Never write comments again.

Open a file you didn't write. Scroll past the imports. Count the comments.

There's the one that lies — "returns null on failure," above a function that throws. There's the TODO from 2021. Then two hundred lines with nothing at all.

Every engineer knows this file. Most of us wrote it.

The economics never worked.

Comments aren't missing because engineers are lazy. They're missing because writing one is a bad trade, and engineers are good at spotting bad trades.

The author pays the full cost now — time, focus, a broken train of thought. The benefit lands later, on someone else. A different person, a different team, sometimes a different year.

And nothing enforces the trade. No build breaks on a missing comment. No test fails on a wrong one.

So the comment doesn't get written. Rationally.

Then they rot.

The few comments that do get written start dying the day they merge. Code changes under review, under pressure, under deadline. The comment doesn't.

A missing comment tells you nothing. A stale comment tells you something false — with the full authority of documentation.

That's the real damage. You trust the comment, skip the code, and ship the bug the comment said couldn't happen.

Teams learn this the hard way, then adapt. Stop trusting comments, then stop reading them, then stop writing them. The rot finishes what the economics started.

The last manual task.

Consider everything else we stopped doing by hand. Formatting went to formatters; testing went to CI. Builds, deploys, dependency bumps — automated one by one, until the repetitive work belonged to machines.

Documentation is the exception. It's the last repetitive task in software still done by hand — which mostly means not done at all.

It survived automation for one reason: describing code requires understanding it. Machines could always parse code; they couldn't explain it. Now they can.

Documentation is a build artifact.

That changes what a comment is. Not something you write — something derived. The knowledge was always in the code, and the code is the source of truth.

So treat documentation like compiler output: generated from source, regenerated on every change, disposable and reproducible. Delete it and nothing is lost, because it was never the original.

Generated documentation stays synchronized with the implementation because it comes from the implementation. Nobody maintains it, so nobody can forget to.

Living documentation isn't documentation you keep alive. It's documentation that regenerates.

What's still yours.

One kind of comment can't be derived. Code says what it does; only you know why.

"Why does this exist?" is a human comment.
"This function deletes expired sessions." is not.

CodeComments writes the second kind, as a draft you review. Generated doesn't mean unreviewed — the review is where your judgment enters. The first kind stays yours.

We don't compile by hand.

We stopped writing assembly, and nobody mourned. We stopped formatting by hand, deploying by hand, resolving dependencies by hand.

Each time the pattern was the same: the machine took the mechanical work, and engineers kept the judgment. Each time it felt inevitable in hindsight.

We no longer compile by hand.

We shouldn't document by hand either.