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
That only happens if people editing the code do not see comments as valuable and important. The fix is easy: Unterstand the code, its changes in the version log, and update and correct the comments as you change the code.
And: If LLM tools could really understand code, it would be easy for them to check changed code and point out where code and comments do not match any more - and why.
The worst, I think, is to have all three of specs and requirements, code, and comments and documentation generated by LLMs.
Because then you have nothing which is checked by a human whether any of it makes really sense.
If the LLM tool just implemented a signature/spec/architecture wrong that was written by a human, this would be easy to fix later, without messing up the interfaces within the system. Not so if you have ai Spaghetti code created without human understanding.