Re: coding style, continuing education

[Phil Edwards <pedwards at disaster dot jaj dot com>]

On Fri, Jan 19, 2001 at 05:46:33AM -0500, 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>

That's pretty much the style I use; as Tom says, the pre-function comment
is the most important one.

The Linux coding style file has some interesting comments (no pun) to make:

#   Also, try to avoid putting comments inside a function body: if the
#   function is so complex that you need to separately comment parts of it,
#   you should probably go back to chapter 4 for a while.  You can make small
#   comments to note or warn about something particularly clever (or ugly),
#   but try to avoid excess.  Instead, put the comments at the head of the
#   function, telling people what it does, and possibly WHY it does it.

Chapter 4 starts off:

#   Functions should be short and sweet, and do just one thing.  They should
#   fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
#   as we all know), and do one thing and do that well.

The 60-line 'if' expressions pretty much blew that test.

Of course, this is also the file that starts off by recommending that the
prospective coder print out a copy of the GNU coding standards and burn
them as a symbolic gesture.  :-)  Which I must admit I've been tempted to
do on many occasions, but that's not germane to the discussion...


-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.