A comment is worth leaving. I’ve come round to thinking there isn’t one that explains what the code does. If you need a sentence to say what a block is for, the block is telling the wrong story. Rename the function. The comment disappears because nothing needed explaining.
People hear when I say this that I want no comments at all. A comment that explains why, or cites the paper the algorithm came from, or records the incident that made this branch exist, is doing work the code cannot do. That kind of note belongs next to the module and ages fine. The one I want gone is the running narration, the line above the loop that says what the loop does. Those rot first, because the code underneath them changes and the sentence above it doesn’t.
This is not a style preference. A comment is a second copy of the meaning. The code does what it does and the comment says what it used to do. The reader now has to decide which one to believe. That’s worse than no explanation at all, because the wrong one is right there in the same file looking authoritative.
Agents have made me firmer on it rather than softer. A developer reading a vague function works the intent out from everything around it. An agent takes the function name and the comment at face value and builds on whichever it read last, so a lazy name becomes the vocabulary for the next twenty files. The code is the meaning because the code is what gets copied.
If the meaning isn’t obvious, the move is always the same: rename the function, split it, improve the parameter names. Look again and look harder before you reach for the comment.
The full write-up is at https://prickles.org/tenet/self-documenting-code/F5
I’ve always hated AI comments. They’re the bastard fusion medium blog spam and data labelling from underpaid and exploited people seeping into the slop.
Comments are for why, edge cases, and caveats. They should help explain unintuitive behaviours that usually must be learned the hard way, they help expose a larger structures, they explain an optimization, a shim, or a complex regex, or they explain where a temporary measure exists. Things of that nature.
Self documenting code is about thinking of the reader. I’ve worked in places that uphold self documenting code as gold and banned code comments at all and I’m convinced that’s wrong. It’s a burden on readers to have to go through history to find the addition, but the file has changed names or moved without a proper git mv and it’s a waste of time.
On that note, learning objective C and Swift did a lot for how I think about what naming could be. I try to focus on clear verbs and nouns so the action and target are always clear, avoid side effects, include examples in my docs, and embrace typing structures like nanedtuples in untyped languages.