To comment or not to comment

Joacim Andersson — Fri, 18 Sep 2009 15:52:49 GMT

Introduction

Anyone that has ever taken a programming class or read a beginners book on the subject know how important it is to write comments in your code. But is that really true? In this post I’m going to discuss/question the common practice of writing comments in your code.

Bad comments

A couple of weeks ago I was contacted by an old friend of mine that runs a construction company. They have an old custom system that they’ve had since the mid or late '90s sometime. He wanted some slight modifications made to this system, but the consultant business that created it apparently disappeared sometime during the dot-com death era. So he wondered if I could have a look at it and come up with an estimation of how much work it would require to do these customizations he needed.

Since he had all the source code - and because I’m such a nice guy – I asked him to e-mail the source over to me, which he did. When I opened up the old project (which was written in Visual C++ 6.0) the first thing I saw in the main file was this (the name of the developer and company have been changed to protect the guilty).

/***********************************************************************************
*
* File name   : CGMain.cpp
* Developed by: John Doe
* Company     : Former Dot Com Inc
* E-mail      : john.doe@nowheretobefound.com
* Date        : 1997-03-21
* Requirements: None
*
*-----------------------------------------------------------------------------------
* Version history
*-----------------------------------------------------------------------------------
*
* 1.0.0 Initial release
*       1997-03-21
* 1.0.1 Minor bug fixes
*       1997-03-24
* 1.0.2 Added 2 functions: AccViewF() and AccViewT()
*       Reason: The customer needed to store the AccView creator and delivery
*       1997-04-03
* 1.0.3 Minor bug fix
*       1997-04-05
* 1.0.3 .... This goes on and on ...
*  ...
*  ...
* 1.2.7 Minor fix
*       1998-04-02
*
***********************************************************************************/

I can assure you that the list was lot longer than what I posted here. What is this good for? Why does a file need a comment header that tells me the name of the file? I already know which file I opened. Do I really care who wrote it? I don’t know that person and the contact information isn’t correct anyway. Could somebody explain to me why you would need a version history typed into the file? Ever heard of source control systems? Those are made to keep track of different versions of your file. The above comment doesn’t bring any useful information my way, or to my friend who isn’t a developer and because of that never even looked at the source code. All it did was made me scroll down a page or two before I got to the actual code.

I can understand that a company that sells class libraries and components with accompanied source code might want to add a (hopefully short) copyright notice on top of each file, but other than that there is really no reason why you want to have a commented header in your file.

When to add comments and when not to

In .Net there is one type of comments I always recommend people to use and that is XML comments. Those are great when they are added to methods and properties of a class library. A library, I might add, that you probably never open up the source code for, at least not if it comes from a third party. The XML comments aren’t meant to be read by humans, they are read by the compiler and shows valuable (hopefully) information in IntelliSense tooltips. Other helpful comments are JavaDoc and PyDoc comments used respectively in Java and Python to create documentation.

I remember once reading a blog post by Jeff Atwood about this very subject, please hold on while I Google it for you……. ah, here it is. Jeff also wrote a long rant about header comments, much like the one above. However in his post he, more or less, said that you shouldn’t use comments at all, which I don’t fully agree with him on. But he has a very important point which I think is also an excellent advice, always aim to write, or refactor, your code so it doesn’t need any comments. With that I (and I think also Jeff, even though I can’t really speak for him) mean that you should always give your methods a very descriptive name, keep them short and to the point.

But unlike Jeff I still think it can be valuable to sometimes stick in a short comment that explains what the code is doing. However you must remember that the comment is then as important as the source code. If you refactor or change the source it is important that you also update the comment. Nothing is as useless as a comment that isn’t valid anymore.

A while back I saw the following comment in the code behind file of an ASP.Net page.

'TODO: The following code is very resource-intensive and
'      should be refactored.

The page that contained this comment had been in the web application in question for years. I looked at the code and couldn’t figure out what it was that was so resource-intensive. I stepped through it, and analyzed it very carefully without finding anything special. So somebody must at some point have done what the comment said, but without removing the comment, which made me waste my time to analyze perfectly working code for no reason at all. Here’s another comment from the same project.

'This is probably not a good idea, 
'and should be changed but I’ll leave it for now.

Excuse me while I scream and swear… (this text has been censored). What is it that isn’t such a good idea? How am I to know how the original developer was thinking when he wrote the above comment? Did he have a brilliant idea how the code could be refactored but was to lazy to do it now? Has he refactored the code but yet again forgot to remove the comment?

The point here is to never write comments that only make sense to yourself. Code is written once and read many times. Much of the code you write today are legacy tomorrow when you aren’t around anymore and some other poor sob have to update it. Always edit or remove comments when you edit the source.

At this point it probably sounds as if I think you shouldn’t write any comments at all with the exception of XML comments, but that is not the case. As Joel Spolsky have said: Code is easier to write than to read. That is so true. How often haven’t you looked back at some code you wrote just a couple of months ago and wondered: How was I thinking here… Not that you weren't thinking when you wrote it, the code is probably just fine, but at the moment you can’t remember the flow of the source. When you develop you are in the middle of it and probably know exactly why you should call that particular method from this particular place, but a few weeks later (after you’ve been working on something very different) when you revisit your older code you just can’t remember that flow. So it takes a while before you are up to speed with it again. Now, what if that isn’t you that revisit your old code? Somebody else that thinks in a different manner than you will have a much harder time to get the flow before he/she can be productive with your source. This is the main reason why developers want to work on new projects all the time. We usually don’t like to work with old legacy code, especially old code we haven’t written ourselves.

In those cases a few well placed comments might help a lot. Just keep remembering that you need to refactor the comments just as much as you need to refactor the source code.

End words

There are one type of comments I do enjoy to read, and that is your comments on my blog posts. :)

Have fun!

Joacim's view on stuff : comments

To comment or not to comment