Myths About Code Comments 580
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?')."
No Comment (Score:5, Funny)
No Comment
Re:Has No One Actually Studied This? (Score:1, Funny)
In thirty years of programming, I've heard one person after another argue about how to comment and how much to comment, but what I've never seen is any kind of serious study attempting to measure what actually works best.
// TODO: Implement mathematically optimal commenting
every line of code should be commented (Score:5, Funny)
Every line should be commented, like: // Declare function called doit with one int param that returns an int // 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. // 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. 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. // Begin an if block using a brace (this is C syntax!!!) // Declare an int variable named j that is one less than i // 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.
int doit(int i)
{
if(i == 0)
return 0;
else
{
int j = i - 1;
return i + doit(j);
}
}
There! Now that is both way readable and informative. Anything less would just not pass my code review.
Re:So who is this guy? (Score:3, Funny)
Warning - war story ahead (Score:5, Funny)
- 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 (Score:4, Funny)
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. (Score:3, Funny)
Re:Has No One Actually Studied This? (Score:3, Funny)
The obvious solution then is to simply ban employees from using comments in code.
Re:One person's myth is another person's fact. (Score:4, Funny)
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 (Score:4, Funny)
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) [xkcd.com]
Re:One person's myth is another person's fact. (Score:1, Funny)
Holy crap, is there a way to upload this to my kindle so I can read it in its entirety on my next plane flight?
Re:Kernighan (Score:1, Funny)
yeah what the fuck did this Brian Kernighan fellow ever do that I should listen to what he has to say about coding ;)
Re:One person's myth is another person's fact. (Score:3, Funny)
Since you have never seen his code and know nothing about its application, it would seem you carry around the "refactor it!" hammer.
It seems that both of you are carrying around the "with a hammer everything is a nail" analogy hammer.