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