httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Richards <p...@originat.demon.co.uk>
Subject Re: I *don't* want Paul's style guide.
Date Mon, 01 Jul 1996 17:57:31 GMT
In reply to Robert S. Thau who said
> 

I think the tone of this reply was a bit harsh and there's a later
reply by me that addresses what I could find of currently open issues.

>   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.

Well, it was there.

> 
>   I've admitted defeat on the function declaration
>   issue and fixed up all I could spot and made the few other changes that
>   I remember people noting. 
> 
> So you *were* deliberately dragging your heels on the clear outcome
> of a vote to try to impose your preferences on the rest of the group,
> even after the nominal basis of those preferences ("you can grep for
> the definitions") was shown to be of little merit (you can grep for
> them anyway).

Hang on, I made a quick first cut at revising it and there was no closure
on any of the issues, people were still voting, we never said, right this
issue is closed. Now that we've gone a few revisions it's clear what the
consensus on function declarations is and the document now reflects
that. I'm trying to edit the document frequently as opinion converges
but it raises a lot of issues we never considered.

> You did.  In fact, you missed some which had been clearly addressed to
> you well before the weekend, viz. both enums and function-declaration
> style, which you *still* haven't got right, despite repeated
> corrections.  If you wanted to do a decent and conscientious job as
> redactor, you should have been saving all this mail, or at least have
> gone through the archive after the fact.  See below.

I did save all the mail I saw, but it has been a busy day so I
mentioned that so people could give me a little slack if I missed
something. I don't do this for a living!

> 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

These were never in our original voting list and so I've left them alone.
This goes for everything in the document for which no vote was taken,
consider them new proposals, not all them I agree with myself.

> 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*.  

I don't think writing from scratch would help since as shown above there are
a number of issues in the doc that we simply never thought of in our
original voting list which is why I thought presenting the doc was a good
idea. We need to list the ones that we never thought of and start voting
on them. I've done this in my latest mailing.

> 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,

but we never even thought of them, in that sense the doc has done a lot
of good.

> In any case, here are the things that leapt out at me in reviewing
> Paul's current attempt.  Paul, if you do another one, I would expect
> to see all of these either dealt with, or moved to a separate, clearly
> delineated section of contentious items.

Excuse me! I don't work on demand! I will continue to do my best to
incorporate the current feeling of this list, remarks such as the above
are totally uncalled for. I don't *expect* you to jump to do things when
I think they need to be done. In any case, I've already done what you
requested in my last mail.

>   /*
>    * 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?
>  */

This is the first dissent from the document on this issue, if no-one
complains then we can't discuss them can we? This will now be added to the
list of open issues.

> /****************************************************************
>  *
>  * As a sole exception, I will sometimes head a *group* of related
>  * functions in a file by a "section divider" like this.
>  */

Well, we never actually voted on it but the "consensus" was against "boxed"
comments like this.

> 
>   /* Enum types are capitalized. */
>   enum enumtype { ONE, TWO } et;
> 
> As noted elsewhere, they aren't in existing code, and I don't much
> like the practice.

Already listed as an open issue, we never discussed this before I presented
the document either.

> 
>   /*
>    *
>    * Major structures should be declared at the top of the file they are
>    * used in, or in separate header files, if they are used in multiple
>    * source files. Use of the structures should be by separate declarations
>    * and should be "extern" if they are declared in a header file.
>    */
> 
> 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.  

I agree that if a structure is only used in a single file then it
should be in the file where it is used.

> (As a side note, the formatting of this comment does not conform to
> your own guidelines above).

Can you give me some details.

>   /*
>    * All major routines should have a comment briefly describing what
>    * they do. The comment before the "main" routine should describe
>    * what the program does.
>    */
> 
> "Major".  There's that word again.  I note, BTW, that the example code
> following is indented eight spaces...

Well, use *some* common sense, "major" is an important/complex routine
that needs some explanation. There has to be some judgement exercised here,
trivial routines don't need long comment boxes explaining what they do.

The 8 spaces is due to using tabs. Set your tabstop to 4 and it's
4 space :-) Use of tabs was mentioned but never voted on or even really
discussed. I've put in a proposal on this in the doc but you obviously
missed that paragraph.

> 	/*
> 	 * Space after keywords (while, for, return, switch).  No braces are
> 	 * used for single statement block.
> 	 *
> 	 * Forever loops are done with for's, not while's.
> 	 */
> 
> This I agree with, actually... but it does not seem to reflect group
> consensus.
> 
> 	for (;;)
> 		stmt;
> 	
> 	/*
> 	 * 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.

I don't agree with this. It can actually cause more head scratching if
you have variables declared inside blocks that aren't accessible elsewhere
in the same routine. This is also now an open issue but this is also
the first time its been raised.

> 	/*
> 	 * 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.

Ok, so what's the problem. When the vote is in I'll modify the document, again
this is listed in my latest mail. I've stated several times that this is
a *discussion* document, it's not *my* style preferences, it's a starting
point which we can revise as we find points we disagree with. It seems
to be causing you so much frustration because it's got a lot of stuff in
it that we haven't even begun to address yet and in that sense it's been
a good thing. I doubt we'd have ever thought about a lot of the issues unless
I'd posted the original.

>    /*
>     * 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.

We never agreed that.

> 	/*
> 	 * 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).

Again, a new issue we never previously discussed. I'm thinking about this
one since it's something I've done in my code but I can see some merit
in making the initialisation explicit elsewhere for clarity.

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

Not relevant. We're discussing future style, current style obviously has
a lot of relevance but a lot of the current style is bad which is why
we're discussing this in the first place.

-- 
  Paul Richards, Originative Solutions Ltd.
  Internet: paul@netcraft.co.uk, http://www.netcraft.co.uk
  Phone: 0370 462071 (Mobile), +44 1225 447500 (work)

Mime
View raw message