There was a lot of disagreement on the value of code comments after my earlier post Comments considered harmful.
Perhaps the most important objection that was raised was the idea that it’s OK to improve the code, but it’s even
better to keep the comments in addition to the improved code.
As one of the critics expressed it:
No, comments are there to comment. Period.
That has nothing to do with how good is your code.
You can write perfectly clean code and add good comments to it. Nothing wrong with that.
This is one of those ideas that seem obviously true in theory, but fail to work in practice.
The reason is that comments get out of sync with the code. The comments rot, or rather, their
meaning does. They become more and more misleading as the code gets changed and the comments
are not adequately updated.
Let me give you an example.
But first, I want to make it clear that I don’t think code comments are always a bad thing. Sometimes, they are necessary.
But much less often than people think.
API documentation is often indispensible, but that’s really a different matter.
When API documentation is generated from comments in front of each method,
the primary purpose is to explain how the code can be used, not how it works.
In fact, you might say they are code comments only in a syntactical sense.
On to the example. One of the comments to my blog post presented a code snippet that illustrates my point well. It’s supposed
to be a example of a useful inline comment in code.
// first handle the case where no records were found (if $records == 0) { return false; }
Is this really an case of good commenting? I don’t think so. If it’s hard to
understand that $records == 0 means that no records were found, we can change
the code to make it easier. The simplest way to do it is to rename the
variable to something like $numberOfRecordsFound or $numRecordsFound. Or
extract a method. But typically, it’s possible and preferable to avoid this
kind of check altogether.
Anyway, the comment is unnecessary. But as I only realized
a while later, it’s also misleading. Does the code “handle the case
where no records were found”? No, it leaves it to the calling function to
handle the case. The one line that returns false is not handling anything, it’s just
passing a message.
So the comment is already misleading, never mind what will happen when someone
changes the code and neglects to update the comment. For example, let’s say the
next programmer to work on this code is in hurry to fix a bug. Now maybe the
code will look like this:
// first handle the case where no records were found (if $records == 0 && $state == ACTIVE) { return false; }
The programmer wonders briefly whether the comment is still fully appropriate,
is unsure, and decides to do nothing about it (or postpones the decision and
forgets about it). Now, perhaps (we can’t quite tell without the full context), the comment is even more misleading.
In the next round, yet another programmer comes along, makes some more code changes
and wonders: “Should I update the comment? It looks all wrong to me, but it was
probably written by someone with deeper insignt into the code. Better leave
it alone.”
The code would have been better off without the comment, but no one wants to
delete it, especially since they have been told that comments are so important.
It’s a downward spiral: the code changes make the comments misleading
less chance that they will
Comments that lie are worse than no comments, and in practice they tend to big liars.
