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

  • HaraldvonBlauzahn@feddit.org
    8·
    7 days ago

    This is a fantastic discussion on the issue:

    https://github.com/johnousterhout/aposd-vs-clean-code

    In brief: Robert “Bob” Martin, author of “Clean Code”, could not explain an algorithm he published himself in his own book. He published it without comments.

    He was also not able to change it without breaking it, because he did not understand the invariants in the code he published.

    Bonus points for that he copied the algorithm from Don Knuth, who published it as an example for his lucid invention of “Literate Programming” - a method to better explain code and its pre-conditions and invariants, by interspersing explanatory text with the actual code.

    Extra bonus points for that the algorithm which Don Knuth documented was first published by grandmaster Edsgar Dijkstra in “Notes on Structured Programming”. A brilliant book chapter which explains once and for all invariants in code and data structures.