(^34) 97 Things Every Programmer Should Know
Comment Only
What the Code
Cannot Say
Kevlin Henney
THE DiFFERENCE BETWEEN THEORY AND PRACTiCE is greater in practice
than it is in theory—an observation that certainly applies to comments. In
theory, the general idea of commenting code sounds like a worthy one: offer
the reader detail, an explanation of what’s going on. What could be more help-
ful than being helpful? In practice, however, comments often become a blight.
As with any other form of writing, there is a skill to writing good comments.
Much of the skill is in knowing when not to write them.
When code is ill-formed, compilers, interpreters, and other tools will be sure
to object. If the code is in some way functionally incorrect, reviews, static
analysis, tests, and day-to-day use in a production environment will flush
most bugs out. But what about comments? In The Elements of Programming
Style (Computing McGraw-Hill), Kernighan and Plauger note that “a com-
ment is of zero (or negative) value if it is wrong.” And yet such comments
often litter and survive in a codebase in a way that coding errors never could.
They provide a constant source of distraction and misinformation, a subtle
but constant drag on a programmer’s thinking.
What of comments that are not technically wrong, but add no value to the
code? Such comments are noise. Comments that parrot the code offer noth-
ing extra to the reader—stating something once in code and again in natural
language does not make it any truer or more real. Commented-out code is not
executable code, so it has no useful effect for either reader or runtime. It also
becomes stale very quickly. Version-related comments and commented-out
code try to address questions of versioning and history. These questions have
already been answered (far more effectively) by version control tools.