How are we doing?

[Molle Bestefich]

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.