This is the mail archive of the
mailing list for the GCC project.
Re: coding style, continuing education
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Subject: Re: coding style, continuing education
- From: Tom Leete <tleete at mountain dot net>
- Date: Fri, 19 Jan 2001 07:37:50 -0500
- CC: nix at esperi dot demon dot co dot uk, gcc at gcc dot gnu dot org
- References: <10101191046.AA12218@vlsi1.ultra.nyu.edu>
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.