How are we doing?

[David D. Hagood]

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.