coding style, continuing education

[Tom Leete]

Richard Kenner wrote:
> 
>     with a thoroughly misleading comment above it (is that what the entire
>     conditional does? no, it's what the first clause does),
> 
> That raises an interesting issue: where *does* the comment for what the first
> clause does go?  I've been putting it before the entire statement, but,
> as you point out, that's not ideal.  Should we be doing something like:
> 
>         /* This tells when we need to ....  */
> 
>         if (
>             /* We need to if ... */
>             <conditional expression>
>             /* ... or if ... */
>             <next conditional expression>

I think the comment before the entire statement is the most important. It
should, IMO, document the relation between the conditional and the
consequent; not just the meaning of the conditional. If a short abstract
description of the conditional cannot be produced to justify the entire
statement, then words to the effect of "some conditions require that we..."
should be used, with further comments for each independent clause.

In a nutshell: Don't comment to interpret the language for novices, always
say why the consequent block must be done given the condition.

Tom