Mike McCormack wrote:
/* My tests reveal that it's done this way */ /* FIXME: this is broken */ /* go forward in the array */
Then you've got the whole issue of maintaining the comments in synchronization with the code.
You've gravely misunderstood what good code commenting is?
Good comments tell what the _purpose_ of a block of code or a whole function is. The purpose of comments is to let strangers get approximately acquainted with how the code works in abstract, what the call structure is, etc. - NOT to document what individual lines of code do.
Comments that simply state what the code right in front of you effectively does are of course useless. That goes both for dumb oneline comments like the ones you stated earlier, but also for comments that just describe what effects come from nesting a block of code like this and that.
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.
You're missing the point.
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
Sure, that would help with understanding the call structure. But your angle of attack is utopian, since making up function names perfect enough to convey all needed information in the context of all callers, and always structuring code perfectly - especially when the code has to work exactly like Windows code - is practically impossible. And getting everybody to do it is even worse.
Teaching people to write good comments is infinitely easier - it's a simple case of banging 'em on the head and forcing them to write a comment every time they've done a piece of code that they know required cunning skill for whatever reason. You may need to perfect the english phrasing from some of the foreigners around here once they learn to actually write the comments, but that's a minor nit.