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
There is no such thing as self documenting code. In any project the code can only ever tell half the story, the rest must be documented. Even then, I don’t always want to have to go back and figure out what each part does. There is a reason basically all code repos also have built in wikis.
int a; // integer aOkay, and where is the rest of your code?
Why do you need more code? This has comments. It’s perfectly clear.
The other comment I constantly see is the function header that’s obviously copy-pasted from another function and literally nothing changed to reflect the function it’s meant to document. Not the return type, not the parameters, not even the function name.
Or the “helpful” ones that were once true but no longer are due to subsequent changes, which waste more of your time than if they never existed.
Comments are a smell.
Because if you are going to be a pedantic asshole and miss my point then so am I.
I literally mentioned code repo wikis…
Honestly though, it doesn’t seem like you have ever worked on a large project with multiple devs if that is really what you think.
😄
I wrote code for FDA Class III medical devices. Dozens of engineers, plus a controls team, plus a design verification team, plus a regulatory team. At a real company, not some hopeful startup.
Real engineers don’t look at comments, they look at code.
And unit tests.
And SITL tests.
And requirements, which are called-out in the tests.
And FMEAs.
Keep your comments. They do more harm than good.
Okay, obviously rage bait. Don’t feed him