| 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.";
result.Add(jokeStub);
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);
}
else
{
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?
The return value comment on the GetMostPopularJokes routine, returns a ‘generic’ list of jokes, while the method returns a list of most popular jokes.
I know that ‘generic’ is referring to a generic list though one could read it as well as a reference to the mediocrity of the jokes returned
Comment by Frans Bouma — December 11, 2008 @ 9:20 am |
Hey Frans, good catch. And here I am speaking of code reviews ….
I’ve amended it so as not to confuse the innocent readers. I failed trying to come up with a better joke though…
Comment by Freek Leemhuis — December 11, 2008 @ 11:46 am |
[...] The comment of all comments « Freekshow 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? [...]
Pingback by Head.SmackOnTable(); » Blog Archive » Commenting (And testing ScribeFire) — December 11, 2008 @ 1:28 pm |
[...] Get more after the jump at .NET Developers Blog [...]
Pingback by The comment of all comments | Tech Trend Watching — December 13, 2008 @ 2:35 am |
Great entry, I’m 100% in agreement with the no comment policy of Fowler and others. Hell, I’ve been following it for years unknowingly.
Comment by Adron — December 15, 2008 @ 5:05 pm |
Nice to see I’m not the only one with this view… on my own blog (not posting a lot at the moment
) I posted something similar in July 2008.
http://www.markvandenbergh.com/archives/21/no-more-comments-in-your-code/
I didn’t came up the idea myself, but I read about it… and checked the code I was working on that day and I immediately found some good examples of redundant comments.
Comment by Mark — February 20, 2009 @ 10:27 am |
The use of comments in code is always a point of discussion between software developers. In my opinion Martin Fowler is right by stating that comments in code *can* be a code smell, but I think he misses an important point by saying that you have to: ‘try to refactor the code so that any comment becomes superflouos’. Good code is indeed self-explaining concerning the syntax and semantical meaning of the code, but the *intention* of the code: the ‘why a certain approach or algorithm in code was chosen’, can never be read from code.
So in addition to this excellent post I would like to add a quote from the book ‘Code Complete’ of Steve McConnell: ‘write comments at the level of the code’s intent.
Comment by Arne — February 24, 2009 @ 10:39 pm |
@Mark: I’m sure it is not the most original of posts, but I think it’s a point that needs to be made now and then, and I’m glad we agree on the subject
@Arne: I do agree with Fowler, in that you have to try to refactor the code so that comments are no longer required; if you can refactor in a manner that results in an implementation that is obvious and that expresses the intent, I’m sure you’ll agree that’s desirable. And I do think it is possible, there’s plenty of code that you can read and immediately grock the intent of the writer. Good naming of variables, methods and class names can express intent. Unit tests can express intent.
I do agree that this is not enough in some cases, where you might have specific reasons to choose a certain approach. I think we agree that in these cases comments are required.
Comment by Freek Leemhuis — February 25, 2009 @ 9:56 am |