James Carr has written a well argumented post about comments. To sum it up shortly, he says comments are the lowest form of communication, and that commenting freshly written code is not a good idea.
I tend to disagree, and here’s why.
Arguments against commenting
James puts it quite well: When you write comments, it would be much better idea to just talk with your coworkers about it. He uses “excuses” as an example – code which does something that you need to explain, or says something like “Here we do X but we should really do Y”
While I partially agree – if you’re not sure which approach you should use, or whether your approach is correct, talking with your coworkers is definitely a good idea.
While James doesn’t directly say that you should not write comments, it does sound a little like it. He does point out that instead of having comments, code should be self-explanatory and self-documenting. While having code like that is definitely a good thing, sometimes you just need comments.
When comments go bad
Before we look at reasons to write comments and good commenting style, let’s take some examples of bad and useless comments.
//Set user's name $user->name = 'Spike Spiegel'; |
Is this a good comment? If you said no, you’re right.
The reason this is a bad comment is that it does not add anything useful. The comment is merely repeating what the code says. It’s quite obvious to anyone who has written code that in the above case we are indeed setting the user’s name – even if the comment was not there.
$value = 'bad'; //FIX THIS |
How about this one? Nope.
This one is bad because nobody will ever fix it. That’s right, even though it says fix me, and it’s written in all caps, nobody will still fix it. Why? Because it’s not very likely they know what’s wrong with it, and because it’s not very likely to get noticed. Things that need to be fixed should be put into a bug tracker or such, where they will get their due attention.
So we can have some general advice: Don’t write comments that repeat code and don’t write things in code that don’t tell you something useful about it.
What makes a good comment?
Good comments. They are somewhat more difficult to give examples on, because good code doesn’t usually need comments!
//Calculate if two circles intersect $xd = $c2->x - $c1->x; $yd = $c2->y - $c1->y; $diameter = $c1->radius + $c2->radius; $intersection = ($xd*$xd + $yd*$yd) < ($diameter * $diameter); |
However, here we do indeed see a good comment.
If the comment wasn’t there, would you know what’s happening? You could probably have guessed from the variable names, but the comment clarifies it even more. Even better, we could put the above code in a method circleIntersection, and make the code self-documenting. Check my article on self-documenting code, as it’s a very powerful technique!
How do you write a good comment like above? I’ll be honest with you: It can be difficult.
There are some things that you can take into account when deciding whether to write a comment:
- Does this make the intent – in other words, what I meant with this – clear? Research has shown that the intention of the original programmer is the most difficult thing to understand (various books mention this, such as Code Complete)
- Is this in higher abstraction than the code itself? Comments that are at the same level of abstraction as code are hardly useful and often just end up repeating the code.
- Am I using a dynamic language? In languages where parameter types etc. aren’t defined in code, defining the type in comments such as JSDoc is useful.
- Does this explain why I made this specific choice? If you implement a specific algorithm to do something, it might be a good idea to put a comment in why this approach is better than something else.
In addition to above, sometimes you have to write code that’s difficult to understand. A common example is optimized code: Sometimes you just need to optimize a certain routine, and more often than not, highly optimized code can be difficult to read – and that’s a valid place for a comment.
Good comments are difficult but worth it
To sum it up, I think commenting is very useful when done right. It expresses what the original programmer intended, explains things on a higher level so you need to spend less time trying to understand the code, and points out other useful things.
However, good comments can be difficult to write if you’re not used to it. By paying attention to the way you write comments, and actually writing some and perhaps revising them later, will help you become better – same as with most other things related to programming.