Coding Standards.

[Doug Gwyn]

In article <1990Dec7.163617.10916 at athena.mit.edu> scs at adam.mit.edu writes:
>Good programmer's editors have "show matching brace" commands
>which work well in those cases when the code layout doesn't make
>brace matching obvious (or, as you point out, when long blocks
>span pages or screens).

I align { and } vertically so that I can immediately find the matching
brace visually.  It is also worthwhile to attempt to keep the code
simple enough that compound statements don't span too many lines; this
is not always feasible, but it's a worthwhile coding goal.

>Comments like /* end of ^C special case */ or /* end of argument
>parsing loop */ could be useful.  Perhaps that is what your
>standard requires.  I should think, though, that comments like
>these (as opposed to their less-useful brethren /* end for */ and
>/* end if */) would be better requested with a rule like "code
>shall have useful comments" (perhaps with hints like "...such as
>at the beginning (and end) of complicated blocks") than by simply
>declaring that "all closing braces shall have comments."

I agree with the general sentiments that Steve expressed.  Comments
should serve a purpose.  What purpose?  To help a subsequent code
reader understand the code.  A functional specification for this
requirement is recommended, rather than an attempt to achieve the
goal without mentioning it but rather simply specifying a bunch of
syntactic rules that relate only indirectly to the real goal.  One
should learn this from observing the mistakes of legislators.