Collective Wisdom from the Experts 35
A prevalence of noisy comments and incorrect comments in a codebase
encourages programmers to ignore all comments, either by skipping past
them or by taking active measures to hide them. Programmers are resourceful
and will route around anything perceived to be damage: folding comments
up; switching coloring scheme so that comments and the background are the
same color; scripting to filter out comments. To save a codebase from such
misapplications of programmer ingenuity, and to reduce the risk of overlook-
ing any comments of genuine value, comments should be treated as though
they were code. Each comment should add some value for the reader, otherwise
it is waste that should be removed or rewritten.
What then qualifies as value? Comments should say something code does not
and cannot say. A comment explaining what a piece of code should already
say is an invitation to change code structure or coding conventions so the code
speaks for itself. Instead of compensating for poor method or class names,
rename them. Instead of commenting sections in long functions, extract
smaller functions whose names capture the former sections’ intent. Try to
express as much as possible through code. Any shortfall between what you
can express in code and what you would like to express in total becomes a
plausible candidate for a useful comment. Comment what the code cannot say,
not simply what it does not say.