xref: /original-bsd/admin/style/style (revision 27393bdf) 
1/*
2 * Style guide for the 4BSD KNF (Kernel Normal Form).
3 *
4 *	@(#)style	1.14 (Berkeley) 04/28/95
5 */
6
7/*
8 * VERY important single-line comments look like this.
9 */
10
11/* Most single-line comments look like this. */
12
13/*
14 * Multi-line comments look like this.  Make them real sentences.  Fill
15 * them so they look like real paragraphs.
16 */
17
18/*
19 * Kernel include files come first; normally, you'll need <sys/types.h>
20 * OR <sys/param.h>, but not both!  <sys/types.h> includes <sys/cdefs.h>,
21 * and it's okay to depend on that.
22 */
23#include <sys/types.h>		/* Non-local includes in brackets. */
24
25/* If it's a network program, put the network include files next. */
26#include <net/if.h>
27#include <net/if_dl.h>
28#include <net/route.h>
29#include <netinet/in.h>
30#include <protocols/rwhod.h>
31
32/*
33 * Then there's a blank line, followed by the /usr include files.
34 * The /usr include files should be sorted!
35 */
36#include <stdio.h>
37
38/*
39 * Global pathnames are defined in /usr/include/paths.h.  Pathnames local
40 * to the program go in pathnames.h in the local directory.
41 */
42#include <paths.h>
43
44/* Then, there's a blank line, and the user include files. */
45#include "pathnames.h"		/* Local includes in double quotes. */
46
47/*
48 * Macros are capitalized, parenthesized, and should avoid side-effects.
49 * If they are an inline expansion of a function, the function is defined
50 * all in lowercase, the macro has the same name all in uppercase. If the
51 * macro needs more than a single line, use braces.  Right-justify the
52 * backslashes, it makes it easier to read.
53 */
54#define	MACRO(x, y) {							\
55	variable = (x) + (y);						\
56	(y) += 2;							\
57}
58
59/* Enum types are capitalized. */
60enum enumtype { ONE, TWO } et;
61
62/*
63 * When declaring variables in structures, declare them sorted by use, then
64 * by size, and then by alphabetical order.  The first category normally
65 * doesn't apply, but there are exceptions.  Each one gets its own line.
66 * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;".
67 *
68 * Major structures should be declared at the top of the file in which they
69 * are used, or in separate header files, if they are used in multiple
70 * source files.  Use of the structures should be by separate declarations
71 * and should be "extern" if they are declared in a header file.
72 */
73struct foo {
74	struct	foo *next;	/* List of active foo */
75	struct	mumble amumble;	/* Comment for mumble */
76	int	bar;
77};
78struct foo *foohead;		/* Head of global foo list */
79
80/* Make the structure name match the typedef. */
81typedef struct _bar {
82	int	level;
83} BAR;
84
85/*
86 * ANSI function declarations for private functions (i.e. functions not used
87 * elsewhere) go at the top of the first source module.  Use the __P macro
88 * from the include file <sys/cdefs.h>.  Only the kernel has a name associated
89 * with the types, i.e. in the kernel use:
90 *
91 *	void function __P((int fd));
92 *
93 * in user land use:
94 *
95 *	void function __P((int));
96 */
97static char	*function __P((int, const char *));
98static void	 usage __P((void));
99
100/*
101 * All major routines should have a comment briefly describing what
102 * they do.  The comment before the "main" routine should describe
103 * what the program does.
104 */
105int
106main(argc, argv)
107	int argc;
108	char *argv[];
109{
110	extern char *optarg;
111	extern int optind;
112	long num;
113	int ch;
114	char *ep;
115
116	/*
117	 * For consistency, getopt should be used to parse options.  Options
118	 * should be sorted in the getopt call and the switch statement, unless
119	 * parts of the switch cascade.  Elements in a switch statement that
120	 * cascade should have a FALLTHROUGH comment.  Numerical arguments
121	 * should be checked for accuracy.  Code that cannot be reached should
122	 * have a NOTREACHED comment.
123	 */
124	while ((ch = getopt(argc, argv, "abn")) != EOF)
125		switch (ch) {		/* Indent the switch. */
126		case 'a':		/* Don't indent the case. */
127			aflag = 1;
128			/* FALLTHROUGH */
129		case 'b':
130			bflag = 1;
131			break;
132		case 'n':
133			num = strtol(optarg, &ep, 10);
134                        if (num <= 0 || *ep != '\0')
135                                err("illegal number -- %s", optarg);
136			break;
137		case '?':
138		default:
139			usage();
140			/* NOTREACHED */
141		}
142	argc -= optind;
143	argv += optind;
144
145	/*
146	 * Space after keywords (while, for, return, switch).  No braces are
147	 * used for control statements with zero or only a single statement.
148	 *
149	 * Forever loops are done with for's, not while's.
150	 */
151	for (p = buf; *p != '\0'; ++p);
152	for (;;)
153		stmt;
154
155	/*
156	 * Parts of a for loop may be left empty.  Don't put declarations
157	 * inside blocks unless the routine is unusually complicated.
158	 */
159	for (; cnt < 15; cnt++) {
160		stmt1;
161		stmt2;
162	}
163
164	/* Second level indents are four spaces. */
165	while (cnt < 20)
166		z = a + really + long + statment + that + needs + two lines +
167		    gets + indented + four + spaces + on + the + second +
168		    and + subsequent + lines.
169
170	/*
171	 * Closing and opening braces go on the same line as the else.
172	 * Don't add braces that aren't necessary.
173	 */
174	if (test)
175		stmt;
176	else if (bar) {
177		stmt;
178		stmt;
179	} else
180		stmt;
181
182	/* No spaces after function names. */
183	if (error = function(a1, a2))
184		exit(error);
185
186	/*
187	 * Unary operators don't require spaces, binary operators do. Don't
188	 * use parenthesis unless they're required for precedence, or the
189	 * statement is really confusing without them.
190	 */
191	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
192	k = !(l & FLAGS);
193
194	/*
195	 * Exits should be 0 on success, and 1 on failure.  Don't denote
196	 * all the possible exit points, using the integers 1 through 300.
197	 */
198	exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
199}
200
201/*
202 * If a function type is declared, it should be on a line
203 * by itself preceeding the function.
204 */
205static char *
206function(a1, a2, fl, a4)
207	int a1, a2, a4;	/* Declare ints, too, don't default them. */
208	float fl;	/* List in order declared, as much as possible. */
209{
210	/*
211	 * When declaring variables in functions declare them sorted by size,
212	 * then in alphabetical order; multiple ones per line are okay.  Old
213	 * style function declarations can go on the same line.  ANSI style
214	 * function declarations should go in the include file "extern.h".
215	 * If a line overflows reuse the type keyword.
216	 *
217	 * DO NOT initialize variables in the declarations.
218	 */
219	extern u_char one;
220	extern char two;
221	struct foo three, *four;
222	double five;
223	int *six, seven, eight();
224	char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen;
225	char *overflow __P((void));
226	void *mymalloc __P((u_int));
227
228	/*
229	 * Casts and sizeof's are not followed by a space.  NULL is any
230	 * pointer type, and doesn't need to be cast, so use NULL instead
231	 * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
232	 * against NULL, i.e. use:
233	 *
234	 * 	(p = f()) == NULL
235	 * not:
236	 *	!(p = f())
237	 *
238	 * Don't use '!' for tests unless it's a boolean, e.g. use
239	 * "if (*p == '\0')", not "if (!*p)".
240 	 *
241	 * Routines returning void * should not have their return values cast
242	 * to any pointer type.
243	 *
244	 * Use err/warn(3), don't roll your own!
245	 */
246	if ((four = malloc(sizeof(struct foo))) == NULL)
247		err(1, NULL);
248	if ((six = (int *)overflow()) == NULL)
249		errx(1, "Number overflowed.");
250	return (eight);
251}
252
253/*
254 * Don't use ANSI function declarations unless you absolutely have too,
255 * i.e. you're declaring functions with variable numbers of arguments.
256 *
257 * ANSI function return values and braces look like regular functions.
258 */
259int
260function(int a1, int a2)
261{
262	...
263}
264
265/* Variable numbers of arguments should look like this. */
266#if __STDC__
267#include <stdarg.h>
268#else
269#include <varargs.h>
270#endif
271
272void
273#if __STDC__
274vaf(const char *fmt, ...)
275#else
276vaf(fmt, va_alist)
277	char *fmt;
278	va_dcl
279#endif
280{
281	va_list ap;
282#if __STDC__
283	va_start(ap, fmt);
284#else
285	va_start(ap);
286#endif
287	STUFF;
288
289	va_end(ap);		/* No return needed for void functions. */
290}
291
292static void
293usage()
294{	/* Insert an empty line if the function has no local variables. */
295
296	/*
297	 * Use printf(3), not fputs/puts/putchar/whatever, it's faster and
298	 * usually cleaner, not to mention avoiding stupid bugs.
299	 *
300	 * Usage statements should look like the manual pages.  Options w/o
301	 * operands come first, in alphabetical order inside a single set of
302	 * braces.  Followed by options with operands, in alphabetical order,
303	 * each in braces.  Followed by required arguments in the order they
304	 * are specified, followed by optional arguments in the order they
305	 * are specified.  A bar ('|') separates either/or options/arguments,
306	 * and multiple options/arguments which are specified together are
307	 * placed in a single set of braces.
308	 *
309	 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
310	 * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
311	 */
312	(void)fprintf(stderr, "usage: f [-ab]\n");
313	exit(1);
314}
315