Some Comments About Commenting

Lately I have seen far too much undocumented code. It seems that no one really appreciates the power of good commenting anymore.

I'm a pretty good coder, I think, and so are many of the people I work with. But for some odd reason, I don't remember anyone taking comments as seriously as I do.

Commenting is what makes the difference!
Comments are the difference between good code and excellent code, and as such, they make the difference between a good coder and an excellent coder.

Nobody like to comment their code, and I really don't know why, but I suspect a part of the problem is not knowing how to comment code in a good manner, or not recognizing good comments when you see them.

So I've decided to compile a short list of tips for the common coder, who now have to sit and write some comments for the first time in his life.
Here they are, from least important to most important:

9 Tips for Good Commenting

9. Don't write too long, but don't write too short

Writing "War and Peace" in your code will not do anyone good, everybody knows that.
But more often, you will find out comments that are simply not helpfull, all in the name of shorthand writing.

Writing "sets X according to the database value" is far better than "this line of code sets X according to the value that was returned from the database", no doubt about it. However, how many times did you see a comment that said "sets X" and that's it? Writing those extra 5 words won't cost you more than a few seconds, and can save a lot of time to whoever it may be that will read your code in the future.
It might even be you...

8. Not all comments must be operational

Not all your comments need to describe exactly what happens in the next line.
Comments like "don't forget to set variable X", "to activate these settings you must call function F" or "this code affects function F2" can sometimes be more helpful.

Keep in mind that sometimes code segments are copy-pasted - not a best practice, but it happens a lot - and it could help to know which other places the copied code segment affects.

7. Don't leave dead code in comments

If you don't need it, delete it. I know it's hard, but just let it go...

If you have some brilliant piece of code you just have to keep for the next generations, just in case they will need to do something like that in some other place - you can put it on external documentation, write an email, or post it in your favorite forum. If it's not used, don't keep it in the code!

If you suspect a line of code will be necessary in the very near future, you can leave it, but explain what it does. Write a comment before the dead code that makes it crystal clear why you left it there.

6. Beware of copy-pasted comments

Come on, guys, this is the oldest trick in the book. We've all suffered from copy-pasted code gone bad. However, copy-pasted code gone bad usually get fixed quickly, since it's bound to be discovered sooner or later. Copy-pasted comments, on the other hand, just stay in the code and get rotten.

You copy a block of code, with comments, and you just change the variables you need in the code, and you end up with a comment that has nothing to do with the code. The next time anyone will look at this code he wouldn't understand where the comment came from, so he might leave it as it is "just in case"...

5. Use correct language

This is a problem especially with non-native English speakers, that must write their comments in English (such as myself).
I don't expect the comments to demonstrate impeccable writing skills in a foreign language, but every one that has basic understanding of the language can tell the difference between "returns the X object if it exists" and "object X to return or null".

Even if the comment can be understood without using proper English, it will take an extra second or two to understand it. It could also cause mistakes simply because the person who read the comment didn't understand it correctly. Not a life or death matter, but it is still very important.

4. Don't be afraid of repeating yourself

Don't be afraid of repeating yourself. Over and over again, when necessary. The same sentence can appear in 4 different procedures, and maybe a couple of times in the same procedure. Remember, probably nobody will ever read your code like a storybook, as a whole. The reader will not mind that some comments repeat themselves. Sometimes the reader will only look at one part of your code, at one specific function.

It's OK to write the meaning of a variable or parameter in the constructor, setter, and every function that use it. It's more than OK, it's better to do so than to write the meaning of the variable only once in some private function that is only used way down the call stack. This way the programmer will not need to drill down only to discover the meaning of a parameter he is using.

So again, when commenting, don't be afraid of repeating yourself.

3. Don't be afraid to comment the obvious

The important point here again is that nobody will read your code like a book. Nobody will be upset if you write a comment stating the obvious. The fact is for most programmers, even the most experienced, it is easier to read natural language than code. That's just the way the human mind works.

Try to read this simple code and you will understand:

private int multi(int a, int b)
{
   return a*b;
}

You could guess from the name that this function multiplies two numbers.
However, you could not be sure until you read the whole function.
If you read the following example instead:

// This function multiplies two numbers
private int multi(int a, int b)
{
   return a*b;
}

You only have to read the first line to understand it.
If you have a comment for every couple of rows in your code, you don't have to delve into the code every time to understand it, you can find the part you need quickly.

This example may seem a little silly, but this is the same for 5 rows long functions or 50 rows long functions, and hopefully you don't have functions much longer than that in your code :)

2. Comment the why, not only the how

OK, now we are getting serious. Whenever we comment a piece of code, we should not only comment what we are doing and how, we should also comment why we are doing what we are doing.

I have a couple of way to comment this method:

public MyClass(int myProp1, int myProp2, string myProp3)
{
   this._myProp1 = myProp1;
   this._myProp2 = myProp2;
   this._myProp3 = myProp3;
}

I could comment the how:

// This is the constructor for class MyClass
public MyClass(int myProp1, int myProp2, string myProp3)
{
   // initialize private properties
   this._myProp1 = myProp1;
   this._myProp2 = myProp2;
   this._myProp3 = myProp3;
}

But I better comment the why:

// This is the constructor for class MyClass.
// This class does this and that. 
// Classes that creates MyClass should do X, Y and Z.
public MyClass(int myProp1, int myProp2, string myProp3)
{
   // initialize private properties:
   // _myProp1 controls this behavior
   this._myProp1 = myProp1;
   // _myProp2 controls that behavior
   this._myProp2 = myProp2;
   // _myProp3 is displayed on screen when X happens.
   // It can be omitted, and then the default message
   // is displayed.
   this._myProp3 = myProp3;
}

Isn't that a lot better? When reading this code, I know why I need to initialize myProp1 in the constructor, and what is the purpose of doing so.

Commenting the why is the key for good commenting. If you take only one thing from this post, take this.
Programmers are not idiots. They can read code - and if they can't, it won't help no matter how much comments you give them. But a line of code cannot express the meaning or spirit of the whole program. This is why you should comment, to explain the place of this specific line of code in the overall stucture of your system.

And now, for the number one tip of good commenting...

1. Comment

...As opposed to "do not comment", of course.

You know what they say, practice makes perfect - so start commenting today!

Make it a habit to comment your code when you are writing it, not afterwards. It always helps to think a little before you code. So while you're at it, planning how your code will work and all the bits and bytes, you already know why you need to write this piece of code. You know it now, but tomorrow you may forget. Someone else that will look at the code will not know. So tell him why you wrote it, and what it is supposed to do.

Believe me, before you know it you will not be able to code without commenting.


I hope this helps, and if a single helpful comment was born as a result of my post, my work here is done :)