From: rst@ai.mit.edu (Robert S. Thau)
Date: Mon, 1 Jul 1996 12:55:54 -0400
Message-Id: <199607011655.MAA15553@hershey.ai.mit.edu>
To: new-httpd@hyperreal.com
Subject: I *don't* want Paul's style guide.
Sender: owner-new-httpd@apache.org
Precedence: bulk
Reply-To: new-httpd@hyperreal.com

  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.

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

  I may have missed a few, lots of mail when I get
  in on Mondays because I'm usually away at weekends.

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'm afraid these things do not raise my confidence in you as redactor
of this document.  At this point, I'd offer to do it myself, but I
simply haven't got the time --- I don't even have the time to do even
critiques as cursory as the one below; I shall now have to explain to
my advisor why I was writing it instead of chapter six of my thesis.

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

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

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.

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

/****************************************************************
 *
 * As a sole exception, I will sometimes head a *group* of related
 * functions in a file by a "section divider" 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.

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

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

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

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

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


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

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

	/*
         *  Also, test pointers
	 * against NULL, i.e. use:
	 *
	 * 	(p = f()) == NULL
	 * not:
	 *	!(p = f())
         */

!foo is used all over the current Apache code.

rst