Any developer has written at least one line of comment throughout his code. Some have written many comments in an attempt their code to be more explanatory. This article gathers some of the practices used in writing code comments.
The members of the Seattle Area Alt.Net group have discussed the need and practices for writing code comments. Kelly Leahy prefers self-explanatory written code with very few comments interspersed because he believes comments “only introduce incorrect noise into the system” since they tend to “get left behind in the dust when making code changes”:
[writing comments] it's a personal thing for most people, but I tend to lean very strongly against comments because of their propensity to get left behind in the dust when making code changes - I've seen it happen TOO many times where some comment refers to code that no longer exists, behavior that no longer exists, code that isn't immediately after the comment (because
someone inserted a new line of code between the comments and the original code) or says something that simply isn't true anymore, just because the code got changed and the comment was left alone.I find those comments to be so much worse than the lack of comments that I abhor comments altogether.
Leahy does not exclude comments entirely and he is using one line of comment for about 10,000 lines of code:
comments can sometimes be useful when you have constraints on design that can't be avoided (performance changes, etc.) that might require a bit more explanation. I still try very hard to avoid them, and we probably have 1 comment line for every 10000 or more lines of code (except for the silly xmldoc comments, which I personally think are useless noise except in public API work).
Justin Rudd explained that he needed to use many comments in his current project because its API “is so messed up”:
Right now I'm writing a source control package for Visual Studio. That API is so messed up that I have to comment what I'm doing so I remember why in one place I pass Guid.Empty and in another (seemingly similar) that I have to pass a particular GUID or it blows up.
I comment which of the 4 solution event interfaces I'm implementing so that the next person that comes along and sees 6 of the 7 methods seemly stubbed out won't delete them.
I comment why I am returning a particular HRESULT out of a method because when I return S_OK - Visual Studio crashes (and it is documented in Connect).
And I comment that even though the docs say you can pass null, you really can't.
In this project, I probably have a 2 to 1 code to comment ratio.
Chris Tavares uses comments for bug fixes:
The comment "// doing this because it fixes bug #####" is not a smell – in fact it's essential.
But Brandon Molina believes it is better to comment bug fixes using the version control system rather than doing it inside the code:
What happens when 10 bug fixes are made? The code is current and now you have a paragraph of useless information cluttering your code. Use version control for this. Where a comment is combined with a diff and the comment actually has useful context.
Brad Wilson added a guiding rule to avoid smelling comments:
"Why" comments == good
"How" comments == suspect
Writing on code comments, Timo Hilden insisted on the need to include good comments:
It’s easy to disregard writing code comments. Let’s face it, we as coders are not going for the Pulitzer prize, so it’s not about the lack of personal ability of being able to express oneself, it’s just plain laziness.
To be honest, leaving code without descriptive comments where they’re needed is much worse than that. Firstly, it indirectly shows the programmer’s lack of respect towards his peers. Everyone knows how frustrating it is to wade through dozens of classes and even more functions with cryptic, non-self-descripting code, especially when the original coder is on vacation, has left the company or otherwise not unavailable for any other reason. A programmer is an artist, with fellow programmers as the audience. And as all artists, we should learn to respect our audience.
Secondly, leaving out comments shows the programmer’s overconfident attitude towards himself. Sure enough, when writing code, we usually have a good idea of what we’re doing. But programming is often about juggling several things in mind at once, and when you next time look at your code, it may be quite difficult to get back to the mindset you were in when writing the code originally. In these quite common situations, it pays to have descriptive comments in place.
Hilden does not support undocumenting – a practice mentioned by Scott Swigart and Jeff Atwood years ago -, considering the following example as excessive commenting:
// Declare category id for products
const int prodCategoryId = 1024;
// Create an iterator over products
vector<Product>::iterator iter = products_.begin();
// Iterate through all products
for ( ; iter != products_.end(); ++iter )
{
// Assign categody id to each product
iter->AssignCategoryId( prodCategoryId );
}
He suggested combining all the above comments into one explaining the general idea not every step made:
// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}
What practices for writing comments are you using? Are there practices enforced by your company or chosen on your own? Are you supporting the writing-as-few-as-possible-comments policy, believing that the next develop will understand your code, or do you think one should take the time documenting what it is not so obvious?