Date: Mon, 1 Jul 1996 10:16:22 -0700 (PDT)
From: Alexei Kosut <akosut@organic.com>
To: new-httpd@hyperreal.com
Subject: Re: I *don't* want Paul's style guide.
In-Reply-To: <199607011655.MAA15553@hershey.ai.mit.edu>
Message-ID: <Pine.SOL.3.93.960701100344.9171A-100000@acidik.organic.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: owner-new-httpd@apache.org
Precedence: bulk
Reply-To: new-httpd@hyperreal.com

On Mon, 1 Jul 1996, Robert S. Thau wrote:

>   Revised style guide. I've explicitly listed the indentation rules which may
>   or may not be contentious. 
> 
> Perhaps I'm missing British understatement again, but I saw no such
> notations anywhere in your draft.

There was something that said 4, I think.

> However, there are a *lot* of recommendations in the KNF document
> which do not reflect existing consensus, many of which I frankly
> regard as bad practice (i.e. "don't initialize your variables", "don't
> declare variables in blocks").  In fact, the only thing in that
> document which I think I agree with is brace-style for control
> structures.  I would also therefore prefer to see the document either
> written from scratch or based on some document which is closer to what
> the group's actual preferences *are*.  

Sounds good to me.

> Starting from a list of winning entries on Ben's ballots will at least
> avoid dragging in stuff on which no consensus was ever reached.  (Ben,
> if you'd like to do things this way --- you seem to be putting in a
> lot of time on style matters anyway --- you'd have my full support,
> for what little it seems to be worth around here).

I dunno... Ben seemed pretty far removed from the consensus. I think the
"winner" should write it :)

[...]

>   /*
>    * Multi-line comments look like this.  Make them real sentences.  Fill
>    * them so they look like real paragraphs.
>    */
> 
> /* My multi-line comments generally look like this.  Is there
>  * any consensus on the above form?
>  */

I perfer the latter for short multi-line and the former for long
multi-line.

> I'm not sure what a "major" structure is.  At any rate, when a
> particular structure is used only by a given routine or set of
> routines in one file, I think it is by far the best practice to put
> the declaration with them, to keep it close to the use.  

Hmm. This one I'm not so sure about. With the current Apache code, which
follows this rule for the most part, it can get really annoying when you'd
really like to call a function in http_protocol.c from a module, but you
can't, because there's no header file that has it. I suppose on one hand
it encourages writing code that would work on any Apache API-compatible
server (not that there are others), but it can get annoying...

> 	/*
> 	 * Parts of a for loop may be left empty.  Avoid declarations in
> 	 * blocks unless the routine is unusually complicated.
> 	 */
> 
> Agree with the first, disagree violently with the second.  If a variable
> is used in only one block, it ought to be declared in that block, to 
> minimize head-scratching about possible uses elsewhere.

Agreed.

> 	/*
> 	 * Try to put shorter part first.  The closing and opening braces
> 	 * go on the same line as the else.
> 	 */
> 
> Do they?  There's a vote out on this.

I don't think so. (at least, *I* don't think so)

>    /*
>     * Example of function declaration style.
>     */
>    static char *function(int a1, int a2, float a3, int a4)
>    {
> 
> You *still* haven't got this right.  The opening brace goes on the
> same line as everything else, if there's room for it.

Actually, I think for function declarations we had voted to have the brace
on the next line.

> 	/*
> 	 * If a line overflows reuse the type keyword.
> 	 * In general, don't initialize variables in the declarations.
> 	 */
> 
> Again, I disagree strongly with the second of these recommendations
> --- I regard initialization of variables in the declarations, where
> possible, to be good style (so long as initializations are kept one
> to a line, and not admixed with declarations of uninitialized variables; 
> they shouldn't be easy to miss).

Agreed.

> 	/*
>          *  Also, test pointers
> 	 * against NULL, i.e. use:
> 	 *
> 	 * 	(p = f()) == NULL
> 	 * not:
> 	 *	!(p = f())
>          */
> 
> !foo is used all over the current Apache code.

Defenitely. I personally would like someone to explain to me why you'd
ever want to test something against NULL, instead of just letting the
expression evaluate itself. Correct me if I'm wrong, but NULL is usually
defined as either (void*)0 or 0, and either way, it's just 0,
which is the same thing that !foo evaluates to if foo is not 0. And, IMO,
!foo looks a lot cleaner (and shorter).

-- Alexei Kosut <akosut@organic.com>            The Apache HTTP Server 
   http://www.nueva.pvt.k12.ca.us/~akosut/      http://www.apache.org/