How to Write Comments

Last edited: 2006 January 16

Should I write comments? What is good comment? Is it possible to write comment for a class in 5 minutes? I would discuss these questions. I would be happy if, after reading, you will be thinking that good comments are an important thing to your project success.

I must admit that I hated to write comments. I was finding them boring and unnecessary. And the worse thing is that I was afraid that during my design some of my methods or classes might go away together with my time spent for writing my good comments. So the first thing I would discuss is


Why?

Here is the first reason for comments. Comments can make your design clearer. You could mark the class with its responsibilities using comments. You can check then how much your class respects its responsibilities, and that it don’t do something which is not its responsibility. Moreover, you can check how much your class respects Single Responsibility Principle and make some decisions to improve the design.

But I think that primary reason which can force you to write comments is to make your code understandable for others. The rule is simple. If you will hide your code for forever - nobody is going to know if it is commented or not. As soon as you are going to share your code with some other person - unless you are not writing it all together from the beginning - he or she will be happy to see your class comments.

Of course you could be happy to explain it to everyone personally. But you want to avoid phone calls asking what your class does while you are on vacation.

Updates are here!
Some person recommends to comment hard things. Absolutely.
Many people write comments for themself. Hire them now.

Do you know any other reasons which make you to start writing comments? If yes - I will be happy to include them here. Personally I find an important reason to have a good rest on vacation. So the next question will be -


How?

What is good comment? Should we judge how good the comment is by its word count? Should we have each method commented? I would say we don’t, or else our comments could end up time-consuming for us and being boring for our readers.

Antipattern

It’s so easy to mark a class with extended description of its name. We end up with class TransactionManager marked as Represents a Transaction Manager. Would this be descriptive enough? No sense to include this in comments at all. I can read a class name by my own. I would be more happy to see TransactionManager marked as Manages (creates, disposes and provides) transactions.

Personally I find very useful an old proven approach for class comments. CRC cards was used for a long time (since at least 1989) and hugely adopted with modern techniques like Agile Development (see http://martinfowler.com/articles/designDead.html and http://www.agilemodeling.com/essays/agileModelingXP.htm). We can take two good things from there and supply our comments with: class responsibilities, and class names our class is planned to communicate with.

Note that OO design tells our class to respect Single Responsibility Principle. Here is where your comment becomes an important design tool. If you find it impossible to name your class’s responsibility with a single combination of verb and noun – it is a good chance your class is taking too much on itself and should be split. One trick here is - use of manages helps.

Antipattern

Someone might want to describe here how other classes are going to communicate with our class. I would move this information into corresponding class.

We should end up with class comments which are pretty short but descriptive enough. And what about method comments? No clear recommendation for now. I would recommend to name a method as much descriptive as possible. It could make its comment unnecessary. I would mention some exception situations however. For example, I would describe what the method does if no item with given key available. Will it return null? Will it throw an exception?

Ok! Now we know which kind of comments we are going to write. Now the question is


When?

I dislike doing something which will be thrown away. I dislike writing comments which will be thrown away. During my design, I create new classes, play with them, throw them away and create new instead. I would find a way to save my time and write a comment when I have a decent hope my class will remain within the system.

The point to start writing comments is... when the code is ready to be presented for others. This could be the time before commit to a main source repository, or insert your case here. For this time, I have pretty stable class design, and good chance my comments will live long. I am pretty sure with my class’s responsibilities and what classes it will collaborate with. I can spend as much as 2 minutes writing this information as a class comment. Everybody’s happy!