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?')."
No Comment
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 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.
It's New Year's Day. What did you want – "Y2K bug still not here"?
Antiquis temporibus, nati tibi similes in rupibus ventosissimis exponebantur ad necem.
- 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.
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...
Does it run on Emacs?
We don't see the world as it is, we see it as we are.
-- Anais Nin
> they found that in general the more comments in the code, the more problems were reported against i
The obvious solution then is to simply ban employees from using comments in code.
Don't take life so seriously. No one makes it out alive.
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?
Quidnam Latine loqui modo coepi?
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)
The key sequence to access my Slashdot bookmark in Firefox is Alt-B-S. I don't believe this is a coincidence.
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?
yeah what the fuck did this Brian Kernighan fellow ever do that I should listen to what he has to say about coding ;)
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.
Now that I think about it, I'm pretty sure everything I just said is completely wrong.