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?')."

Comments

No Comment

[Anonymous Coward]

No Comment

every line of code should be commented

[caywen]

Every line should be commented, like: // Declare function called doit with one int param that returns an int
int doit(int i) // See above comment
{ // The function's open brace. I like to put braces on their own line. You should too!! BTW, this is C code, so braces are totally the way to go.
      if(i == 0) // Check if i is 0. You know, in C, "==" is the way to compare values, unlike in VB where you use a single "=". Just thought u should know.
            return 0; // Return 0. That is, all the bits of the return value are 0. We could also return i, because i is 0, too. That is, all the bits of i are 0. On a 32 bit system, there would be, like, 32 0's.
      else
      { // Begin an if block using a brace (this is C syntax!!!)
            int j = i - 1; // Declare an int variable named j that is one less than i
            return i + doit(j); // Return the sum of i and the value of calling doit with j
      } // Finish the if block with a C close brace. By the way, we could have written the above code as return i + doit(i - 1) without using the braces.
} // The function's close brace.

There! Now that is both way readable and informative. Anything less would just not pass my code review.

Warning - war story ahead

[tengwar]

My favourite bit of code was about 22 years ago. It was supposed to control some scientific equipment that we had bought from Denmark, and I had insisted on getting the source because of previous problems with the supplier. In summary:

- 6000 lines of Pascal
- 200 global variables
- 3 local variables
- 1 comment - the single word "midlertidig"

Oh, and one bug. Code really was less buggy back then.

Now get off my lawn, you kids.

Re:Kernighan

[zill]

So I should dumb myself down with a hammer before writing code?

I'm not sure how I'd reverse the process before debugging though. Maybe I should have thought of that before the hammer came down...

Re:One person's myth is another person's fact.

[digitig]

Well it is. Sure you lose the LSB but you lose the MSB on multiplication..

You don't actually lose the MSB -- it shifts into the sign bit. But hey, what harm can that do, eh?

Re:Kernighan

[Anon E. Muss]

So I should dumb myself down with a hammer before writing code?

You can do it that way, but I prefer whiskey.

(Obligitory XKCD reference)