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: Style guide
Date Tue, 02 Jul 1996 00:00:32 GMT
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.

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.

> 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).
> 
> I guess I should also include brackets in returns, though this comprehensive
> document fails to mention them.

It does through example.

> > #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?

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

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

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

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


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