Tuesday, April 22, 2008

a vanity comment is a code smell

A "vanity" comment isn't an explanation about the code but the rationale behind why the code is written in a naughty way. Its goal is to remind the reader that the code was indeed written by a professional, appearances notwithstanding. In contrast, the goal of most comments is to aid the comprehension of the code. Comments about legitimate design trade-offs and comments about how the current case is a valid exception are not vanity comments. A "TODO" comment, particularly vague examples like "TODO: rewrite", may or may not in fact be a vanity comment, depending on its seriousness. (Does the writer really plan to revise this section or was it merely wishful thinking that he or she would later have the time?)

The point is, if vanity comments have proliferated throughout the code, then the net indication is that the author is lazy rather than incompetent. He or she knew the shape the code should have taken but unilaterally decided to do what was easier. (Rational laziness, i.e. the calculated reduction of total/overall effort by considering the marginal benefit for each marginal cost, is a different category--cutting corners in a tiny shell script that performs one function is okay, while setting styles of individual web pages/templates through a GUI instead of site-wide CSS will bite you later.) The vanity comment shows that the coder wasn't ignorant. Taken together with the adage "Never attribute to malice that which can be adequately explained by stupidity", the vanity comment seems to imply that since stupidity or ignorance isn't the reason behind the sloppy work, malice is the correct conclusion. The developer who created the sub-par code but was thoughtful enough to hang a lampshade on it hates you, the maintenance programmer! Maybe "hates" is too presumptive a term; "devalues" or "dismisses" might be closer.

Code that contains vanity comments should be examined carefully, because quality was not forefront in the mind that birthed it. The occasional vanity comment, especially related to breaking a dogmatic and/or stylistic "rule", is fine if it provides a credible justification. Vanity comments that substitute for following good practices are not. And those comments raise the question of the thoroughness of everything else.

No comments:

Post a Comment