Slashdot Mirror
Myths About Code Comments
theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."
I find the most important comments are those that tell you WHY something was done the way it was. I do this with my own code when I track down and fix a bug that turns out to be caused by some very subtle effect or easily made mistake. I put the comment there to stop myself (or someone else) from "fixing" / "cleaning it up" later because they don't realize why it's done the way it is. Comments like:
# yes, 1, not 0. If all four of the lists are allowed to go to 0, we will blow up later with DBZ.
And having a sometimes very poor memory of code written long ago, this saves me from myself more than others.
I work for the Department of Redundancy Department.
Wrong on all accounts
RTFA, the article starts out with these two sentences:
It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development. However, I feel that this is a part of programming that's almost as important as writing code itself.
His point is that worthless comments are worse than no comments at all. Unfortunately a large percentage of the comments you see in code today were autogenerated by the IDE and are just noise.
If your comments are that detailed, you're doing it wrong.
It was Brian Kernighan who pointed out that:
"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."
My other car is a 1984 Nark Avenger.
You do realize that some of those types of comments aren't really intended for humans anyway, but more for documentation generators like javadoc and doc++ ?