Caveat commentor

In programming, I’ve come to see the urge to comment as a sign of danger.

Sometimes comments are necessary, but it’s easy to abuse them as a crutch. They give you a way to lapse into fault-tolerant human language in an environment where precise, complete and unambiguous expression is required. It’s tempting to write some muddled code without a full understanding of the problem and then use comments to try to explain the inherent confusion. (Note that I regard comments as distinct from developer documentation. Javadoc, POD, Python docstrings et al follow different rules from comments.)

I find comments necessary in two cases:

1. The code deals with an intrinsically hard concept; no matter how clearly it’s written, it will be hard to follow.

   Here, a comment will help the poor wretch who comes after you to catch on faster.

2. The obvious way of writing something is wrong, but that’s not obvious until you try it or until after you had to fix the bug.

   Here, a comment will extinguish any inappropriate urge to refactor in the poor wretch who comes after you. While you’re at it, write a testcase and reference it from the comment you leave.

If you are not dealing with either of these circumstances, then I find that in general, an urge to comment is a sign that you do not have enough identifiers. If you have a complex expression, use temporary variables to split it up, and make sure to name the temporaries well so that the code explains itself. If you have a “we frobnicate the veeblefitzer here” style comment leading a block of code, then extract that block into a frobnicate_veeblefitzer function instead. In general, rather than writing a comment, you should find a way to bake its essence into an identifier in your code.

Comments rot when code is maintained; they can neither be debugged nor can they be refactored at once with the code they pertain to. Avoiding sideband channels in favour of making the information part of the code is important to ensure that the information remains accurate.

    When the code and the comments disagree, both are probably wrong.
    —Norman Schryer

[NB: it’s another matter entirely if the programmer in question writes muddled code and then doesn’t comment it. In that case, nothing I said here is applicable in the first place. The presence of an intact and well-developed sense of readability, with an associated urge to comment, is a precondition for using self-same urge as a guide in any way.]