Probably everyone knows the famous saying “better no comment than a wrong one”, or one of its variations. And it’s true: it’s extremely confusing reading what a piece of software is supposed do and find out it does something different… Of course, it happens to all of us. You wrote something once, including informative comments. Then you refactor it, then refactor some more, and in having to deal with all the complexities of getting it to work, forget to update the comments.
Here are some best practices for commenting:
Make a clear distinction between black-box and white-box comments.
Black-box comments are things that should be understandable without having to
consult the code. For instance module, template and function descriptions. These
comments must still make sense when they’re sperated from the code, as for
instance happens with XQuery xqDoc (http://xqdoc.org) comments
(between (:~ … :)) in some environments.
White-box comments are about the code. These comments should help the reader to grasp what’s going on.
Do not comment the obvious, comment the intent. This, for instance, is completely superfluous:
<!-- Store the number of <thing> elements in $things-count: --> <xsl:variable name="things-count" as="xs:integer" select="count(//things)"/>
Both the (well-chosen) variable name as the expression already tell you this. This however tells the reader what the intent of the code is:
<!-- Add a prompt attribute to every thing for easier reporting later: --> <xsl:variable name="things-count" as="xs:integer" select="count(//things)"/> <xsl:for-each select="//things"> <xsl:copy> <xsl:attribute name="prompt" select="position() || '/'|| $things-count"/> <xsl:apply-templates select="@* | node()"/> </xsl:copy> </xsl:for-each>
Use comments (and empty lines) for creating “rhythm”. See the section called “The rhythm of the code”.
Use comments as the equivalent of section titles, even if what the comment says is obvious when you know the code. Remember, the reader is’t always that knowledgeable.
<!-- Initialize: -->
…
<!-- Compute the values for … -->
…
<!-- Done, wrap up: -->
…This creates an additional, smaller, rhythm inside the bigger rhythm of templates and functions.
Some movies on DVD (when we used to have DVDs, old-man’s reminiscences) had the option to turn “director’s comments” on. You then heard the movie director in a voice-over about certain scenes: how they were taken, why certain choices were made, etc. One of the best pieces of advise about commenting I ever had was that comments should be exactly like that: like a director telling you about the code.
Why is this code different from the rest? (bug workaround…)
Why this completely incomprehensible expression? (performance…)
What you did to make this working? (prevent problems already solved…)
What trap not to fall into when maintaining this code? (point out obvious mistakes…)
Fantasizing about being a famous movie director and providing comments about your brilliant artistic choices is a constructive mindset for creating high quality comments.
Be very careful with blocks of commented-out code. Don’t make the reader guess about why you left it in. Forgotten to delete? Laziness? Carelessness? Is this still important? Can I delete it now or was there a good reason to keep it? At least provide some comment about the why if you really think it still serves a purpose.