httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ben Laurie <...@gonzo.ben.algroup.co.uk>
Subject Re: Style guide
Date Mon, 01 Jul 1996 23:32:02 GMT
Paul Richards wrote:
> 
> In reply to Ben Laurie who said
> > 
> > If you seriously want this lot to be considered, could you formulate them as
> > votable alternatives. I'll then include them in my list. IMO most of them
> > aren't worth the bother of discussion, let alone the necessary policing.
> 
> Well. someone wlse will have to disagree with them and propose *their*
> alternatives. I've removed some of the stuff but a lot of it does need
> a decision made.

If noone agrees and noone disagrees then I will consider it to be not an issue.

> 
> I think we need to make a quick decision about tabs too since the
> whole lot is affected by it and then make decisions about other dependant
> issues such as brace position since people may feel differently about
> the nitty gritty when some of the basic layout issues are decided.

I think we have made an implicit agreement that indents are 4 spaces, and tabs
are 8 spaces (actually, I think the former is explicit).

> 
> > Exceptions are spaces after ifs/whiles etc. I knew there was something obvious
> > I'd missed. And I'm in favour of commenting flow through in switches (but I'm
> > not sure I like the name "FALLTHROUGH" or the caps).

On second thoughts, I don't think that any commenting requirements should be
a coding style issue.

> > 
> > I guess I should also include brackets in returns, though this comprehensive
> > document fails to mention them.
> 
> It does through example.

And many other things that have not been listed.

> 
> > > #include <sys/types.h>      /* Non-local includes in brackets. */
> > > #include "pathnames.h"      /* Local includes in double quotes. */
> > 
> > For example, this is merely a statement of correct C.
> > 
> 
> It's just as correct to use <..> for local includes but using ".." marks
> them clearly as such.
> 
> The ordering and spacing of include files makes it easy to see what's
> where. If no-one disagrees with this then just include it in the final
> results.
> 
> > > /*
> > >  * Macros are capitalized, parenthesized, and should avoid side-effects.
> > >  * If they are an inline expansion of a function, the function is defined
> > >  * all in lowercase, the macro has the same name all in uppercase. If the
> > >  * macro needs more than a single line, use braces.  Right-justify the
> > >  * backslashes, it makes it easier to read.
> > >  */ 
> > > #define MACRO(x, y) {                           \
> > >     variable = (x) + (y);                       \
> > >     (y) += 2;                           \
> > > }    
> 
> Anyone disagree with the above?

Yes. I have the Explain macro which I want to look like a function call
(because it is).

> 
> > > /*
> > >  * Major structures should be declared at the top of the file in which they
> > >  * are used, 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.
> > >  */
> > > struct foo {
> > >     struct  foo *next;  /* List of active foo */
> > >     struct  mumble amumble; /* Comment for mumble */
> > >     int bar;
> > > };
> > > struct foo *foohead;        /* Head of global foo list */
> 
> Likewise this?

If you mean the placing of the braces, then this is implicitly agreed by
reference to other bracings.

If you mean the comment about "major structures", then define the term so we
can police the policy.

If you mean the indentation of the structure members, I'm prepared to put that
in, though I think that people have indicated that the status quo is OK.

I could go on...

> 
> > > 
> > > /* Make the structure name match the typedef. */
> > > typedef struct _bar {
> > >     int level;
> > > } BAR;
> 
> and this.
> 
> > > /*
> > >  * All major routines should have a comment briefly describing what
> > >  * they do.  The comment before the "main" routine should describe
> > >  * what the program does.
> > >  */
> 
> This is actually important. There's very little documentation of routines
> in the code.

Not a style issue, IMO.

> 
> > >      * parts of the switch cascade.  Elements in a switch statement that
> > >      * cascade should have a FALLTHROUGH comment.  Numerical arguments
> > >      * should be checked for accuracy.  Code that cannot be reached should
> > >      * have a NOTREACHED comment.
> > >      */
> 
> Well, this needs a decision, you've stated you agree with the principle.
> I'd add another, /* NOTREACHED */ should be used after code that never
> 
> > >     /*
> > >      * Space after keywords (while, for, return, switch).  No braces are
> > >      * used for control statements with zero or only a single statement.
> > >      *
> > >      * Forever loops are done with for's, not while's.
> > >      */
> 
> This definately needs voting on since there's disagreement.
> 
> > >     /*
> > >      * Parts of a for loop may be left empty.  Don't put declarations
> > >      * inside blocks unless the routine is unusually complicated.
> > >      */
> 
> and there's vehement disagreement over this.


> 
> > >     /* Second level indents are four spaces. */
> > >     while (cnt < 20)
> > >         z = a + really + long + statment + that + needs + two lines +
> > >             gets + indented + four + spaces + on + the + second +
> > >             and + subsequent + lines.
> 
> I agree with your position about continuation lines, needs ratifying.
> 
> > >     exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
> > >     return (eight);
> 
> Needs voting on.
> 
> > > 	/*
> > >      * Casts and sizeof's are not followed by a space.  NULL is any
> > >      * pointer type, and doesn't need to be cast, so use NULL instead
> > >      * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
> > >      * against NULL, i.e. use:
> > > 	 */
> 
> Needs voting on.
> 
> > > static void
> > > usage()
> > > {   /* Insert an empty line if the function has no local variables. */
> 

If you want these issues to be voted on, I need a list of issues and
alternatives. If there are no alternatives, clearly there can't be a vote.

I'm not fantastically interested in tiny points of style. My main interest is
in where the braces and indents go. The rest can go to hell as far as I'm
concerned.

Can we keep our attention focused on the main issue. Which, in case it has been
forgotten, is writing a Web server. Please.

Cheers,

Ben.

-- 
Ben Laurie                  Phone: +44 (181) 994 6435
Freelance Consultant and    Fax:   +44 (181) 994 6472
Technical Director          Email: ben@algroup.co.uk
A.L. Digital Ltd,           URL: http://www.algroup.co.uk
London, England.

Mime
View raw message