Huw Davies wrote:
There's a bug in this code, let's try this:
/* change by Huw Davies 02-Jun-2006, to fix the return type of the function */ int the_function_that_adds_one_to_i(int i) { /* this adds one to i */ i = i + 1;
/* this returns i to the caller */ return i;}
That's so much better ;-) Huw.
ARRRRRRRG! This whole thing is just a bullshit strawman. The real complaint about the lack of comments is not this kind of trivial comment, but more like:
/* the_function_that_adds_one_to_i - return 1+value This function is necessary because of a compiler bug in FooC 0.8, wherein just incrementing the loop variable in WinGenCryptokeyAllHailBillOurDarkLord will generate incorrect code. */ int the_function_that_adds_one_to_i(int i) { /* this adds one to i */ i = i + 1;
/* this returns i to the caller */ return i; }
There is precious little "Why" in the comments of a lot of projects - Why does this function exist, why would I call it, why does it return what it does, etc.
BS comments like those within the function don't help, obviously - but sometimes a comment block describing WHY a given chunk of code does what it does would be nice.