How are we doing?

[Mike McCormack]

David D. Hagood wrote:

> ARRRRRRRG! This whole thing is just a bullshit strawman. 

Indeed.

However my strawman demonstrates that it's difficult to enforce code 
commenting, as you'll just end up with a bunch of bs.

You also can't comment somebody else's code properly, obvious things 
don't need commenting, and non-obvious things either have a comment, or 
you won't see them.

You can't force other people to add comments, and you can't add them for 
yourself.  So if you like comments, you can jump up and down and say 
there should be more, but that changes nothing.

My pet hate comments are stuff like:

/* My tests reveal that it's done this way */

ofcourse, those tests aren't in the test suite.

/* FIXME: this is broken */

With no explanation of why.

/* go forward in the array */
i--;

Then you've got the whole issue of maintaining the comments in 
synchronization with the code.

If what you really want is code that's easier to understand we're better 
   off scrapping all comments, then enforcing good coding style, so that 
the code is readable without comments.  If the functions are kept small, 
things are well named, and the complexity confined (eg. no 7 level 
indent), you'll be able to understand the code without the auth

If you need to comment your code so others can understand it, it's 
probably badly structured and unclear.

Mike