December 10, 2008

The comment of all comments

Filed under: Programming — Freek Leemhuis @ 9:07 pm
These days I’m doing some code reviews for other people’s projects. Mostly these are architectural reviews, where we review an existing code base and comment on the design of the codebase, and sometimes also on software engineering practices (or lack thereof!).
One of the things that always comes up in discussions is the comments in the code. Tools such as Campwood Software‘s Source Monitor for example allow you to quickly produce a Kiviat Metrics Graph, such as the one displayed below.

There are two different metric values for comments displayed: Documentation comments and actual comments.

Documentation comments

In the graph the value displayed for documentation lines (% Docs) is the number of documentation lines (indicated by ‘///’ at the start of the line) as a percentage of the total number of lines.
These documentation comments show up in the intellisense. For example, if have added documentation lines to the code below:

/// <summary>
/// Get the list of most popular jokes
/// </summary>
<param name="numberOfJokes"  ></param>
/// <returns>Generic List of Joke</returns>
public List<Joke> GetMostPopularJokes(int numberOfJokes)
   List<Joke> result = new List<Joke>();
   Joke jokeStub = new Joke();
   jokeStub.question = "How many developers does it take to change a roll of toilet paper?";
   jokeStub.punchline = "Who knows? It's never happened.";
   return result;

Then if I call the method, the information in the documentation lines are displayed in the intellisense tooltip thingy:

In addition, tools like Sandcastle allow you to compile the comments into help files. Pretty neat?
If you’re Microsoft, and you actually have to deliver this kind of documentation, I suppose it is. In most other cases, I think this type of help documentation is pretty useless. It is out of date as soon as the code is updated, and I have seen on many occasions that the code gets update but the documentation comments are not. And if that does happen, will you ever trust the ‘documentation’ again?
There is no automatic link between comments and the code, and only the most disciplined team of programmers will never forget to adjust comments.
On the other hand, if you use concise variable and function names, should they not express the intent? What does the documentation code add, really?
Usually it is just a (partial) rephrasing of the actual code, and it violates the DRY principle. Have you ever done a lot of refactoring, and keeping the documentation lines up to date at the same time? If you have, I bet you’ll agree with me: this type of ‘documentation’ – let’s do without it.

Actual comments

I find it hard to attach any meaning to code metrics that express the number of in-line comments. It all depends on the purpose of the comments. The following example is from the Enterprise Library:

/// <summary>
// convert to base 64 string if data type is byte array
if (contextData.GetType() == typeof(byte[]))
    value = Convert.ToBase64String((byte[])contextData);
    value = contextData.ToString();

What does the line of comment add? Does it tell you anything that the code does not? Indeed not. Zero points. This kind of gratuitous comments is all too common, and if you have many of these, will you keep reading them? Will you not start to blank out the comments in your mind, thereby possibly missing the important comment that actually does explain a certain coding decision?
Please, only comment if you have something to add!
Would you not agree that having a very low count of comment lines is actually a good metric for quality? That it can be indicative for code that expresses intent very well, with a logical design?
Good code only rarely needs comments.

Martin Fowler, in his book Refactoring, indicates that comments can actually be a smell:

When you feel the need to write a comment, first try to refactor the code so that any comment becomes superflouos.

What are your comments?

Blog at