httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Richards <p.richa...@elsevier.co.uk>
Subject [No Subject]
Date Mon, 01 Jul 1996 14:41:10 GMT

Revised style guide. I've explicitly listed the indentation rules which may
or may not be contentious. 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. I may have missed a few, lots of mail when I get
in on Mondays because I'm usually away at weekends.

Anymore comments?

---------------------------------------------------
/*
 * Style guide for Apache
 *
 * Code should be in ANSI C and not K&R.
 */

/*
 * VERY important single-line comments look like this.
 */

/* Most single-line comments look like this. */

/*
 * Multi-line comments look like this.  Make them real sentences.  Fill
 * them so they look like real paragraphs.
 */

/*
 * Indentation should be four spaces. Tabs may be used at the beginning
 * of lines and set to four spaces. Alignment at the end of lines should
 * NOT use tabs and instead use explicit spaces. Continuation lines may
 * use tabs to the upper indentation level and then spaces for the
 * further continuation line indentation.
 */

/* Include files go at the top of the source module. */
#include <stdio.h>          /* Non-local includes in brackets. */
#include "pathnames.h"      /* Local includes in quotes. */		

/*
 * All function decls go at the top of the source module.
 *
 */
void function(int, const char *);

/*
 * 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.  Put a space before
 * the backslashes.
 */
#define	MACRO(x, y) { \
	variable = (x) + (y); \
	line two; \
}

/* Enum types are capitalized. */
enum enumtype { ONE, TWO } et;

/*
 *
 * 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.
 */
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 */
	
/*
 * All major routines should have a comment briefly describing what
 * they do. The comment before the "main" routine should describe
 * what the program does.
 */
main(int argc, char *argv[])
{
	extern char *optarg;
	extern int optind;
	long num;
	int ch;
	char *ep;

	/*
	 * For consistency, getopt should be used to parse options.
	 * Options should be sorted in the getopt call and the switch
	 * statement, unless they fall through.  Elements in a switch
	 * statement that fall through should have a FALLTHROUGH comment.
	 * Numerical arguments should be checked for accuracy.
	 */
	while ((ch = getopt(argc, argv, "abn")) != EOF)
		switch (ch) {   /* Indent the switch. */
		case 'a':       /* Don't indent the case. */
			aflag = 1;
			/* FALLTHROUGH */
		case 'b':
			bflag = 1;
			break;
		case 'n':
			num = strtol(optarg, &ep, 10);
			if (num <= 0 || *ep)
			err("illegal number -- %s", optarg);
			break;
		case '?':
		default:
			usage();
		}
	argc -= optind;
	argv += optind;

	/*
	 * 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.
	 */
	for (;;)
		stmt;
	
	/*
	 * Parts of a for loop may be left empty.  Avoid declarations in
	 * blocks unless the routine is unusually complicated.
	 */
	for (; cnt < 15; cnt++) {
		stmt1;
		stmt2;
	}

	while (cnt < 20) {
		stmt1;
		z = a + really + long + statment + that + needs + two lines +
		    gets + indented + appropriately + on + the + second +
		    and + subsequent + lines.
	}

	/*
	 * Try to put shorter part first.  The closing and opening braces
	 * go on the same line as the else.
	 */
	if (test)
		stmt;
	else if (bar) {
		stmt;
		stmt;
	} else
		stmt;
		
	/* No space after function names. */
	if (error = function(a1, a2))
		exit(error);

	/*
	 * Unary operators do not require spaces, binary operators do.
	 * Try not to use too many parenthesis unless the statement is
	 * really confusing without them.
	 */
	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
	k = l & FLAGS;

	/*
	 * Exits should be 0 on success, and 1 on failure.  Don't denote
	 * all the possible exit points, using the integers 1 through 300.
	 */
	exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
}


/*
 * Example of function declaration style.
 */
static char *function(int a1, int a2, float a3, int a4)
{
	/*
	 * If a line overflows reuse the type keyword.
	 * In general, don't initialize variables in the declarations.
	 */
	extern u_char one;
	extern char two;
	struct foo three, *four;
	double five;
	int *six, seven, eight();
	char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen;
	char *overflow();

	/*
	 * 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:
	 *
	 * 	(p = f()) == NULL
	 * not:
	 *	!(p = f())
 	 *
	 * Routines returning void * should not have their return values cast
	 * to any pointer type.
	 */
	if ((four = malloc(sizeof(struct foo))) == NULL)
		return (NULL);
	if ((six = (int *)overflow()) == NULL)
		return (NULL);
	return (eight);
}

static void usage()
{	/* Insert an empty line if the function has no variables. */

	/*
	 * Use printf(3), not fputs/puts/putchar/whatever.
	 *
	 * Usage statements should look like the manual pages.  Options w/o
	 * operands come first, in alphabetical order inside a single set of
	 * braces.  Followed by options with operands, in alphabetical order,
	 * each in braces.  Followed by required arguments in the order they
	 * are specified, followed by optional arguments in the order they
	 * are specified.  A bar ('|') separates either/or options/arguments,
	 * and multiple options/arguments which are specified together are
	 * placed in a single set of braces.
	 *
	 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
	 * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
	 */
	(void) fprintf(stderr, "usage: f [-ab]\n");
	exit(1);
}


Mime
View raw message