4 The code in the krb5 source tree largely follows BSD KNF
5 (/usr/share/misc/style on NetBSD) except that it uses a four column
6 basic offset. The style described here is a synthesis of BSD KNF and
7 the GNU coding standards for the C language. The formatting described
8 in the "Formatting Your Source Code" section of the GNU coding
9 standards is mostly what we want, except we use BSD brace style and
10 BSD-ish conventions for the spacing around operators.
12 Formatting style for C code
13 ---------------------------
15 In general, use a four column basic offset, tab stops at eight
16 columns. Indents should be tabified, i.e. continuous tabs followed by
17 spaces if necessary if the indent isn't a multiple of eight columns.
18 The "bsd" style in emacs cc-mode mostly does the right thing. You can
19 use "M-x c-set-style" "bsd" to get this. Alternatively, you can use
20 the "krb5" style that is included here.
22 Labels, including case labels, are outdented by four columns.
23 Continuations of statements are indented by an additional four
24 columns. When continuing expressions this way, split the expression
25 so that the newline goes before a binary operator rather than after
28 Continuations of argument lists or parenthesized expressions should
29 line up with the column after the opening parenthesis. Note that this
30 may create width problems if you call a fuction deep in a bunch of
31 nested control flow statements. Regardless, any expression split
32 between lines should stil be split so that the newline goes before a
33 binary operator rather than after it.
35 The maximum width should be 79 columns. If you need more than this,
36 consider rewriting the code so that it fits in 79 columns, since
37 control flow that is nested deeply enough to require excessive width
38 is also likely to be difficult to understand if not broken up.
39 Exceptions may be made for long strings, though ANSI C string
40 concatenation should work around that as well.
42 Function names for definitions should start on column zero, on the
43 line following their return type name, e.g.
51 [just pretend that's really at column zero]
53 The opening brace of a function definition should also be on column
56 Braces that open substatements, such as those following "if", "else",
57 "while", "for", "do", and "switch", should be on the same line as the
58 begining of the statement. This is sometimes called "hanging" braces.
59 The corresponding closing brace should be at the same indentation
60 level as the beginning of the statement.
62 The "while" keyword in a do-while construct should sit on the same
63 line as the closing brace of the substatement following "do":
69 If there is an "if" statement immediately following an "else" keyword,
70 it should go on the same line immediately after the "else":
78 Comments to the right of code start in column 32. Comments not to the
79 right of code are indented at the prevailing indent for the
80 surrounding code. Make the comments complete sentences. If you need
81 more than one line, make them into block comments, like this:
84 * This is a block comment. It should consist of complete
87 * Paragraphs should be separated by blank lines so that emacs
88 * fill commands will work properly.
91 Really important single-line comments should also be done in block
95 * This is a really important one-line comment.
98 In order to get the start and end delimiters for block comments to
99 stay when you use emacs to fill paragraphs in the comments, set both
100 the c-hanging-comment-starter-p and the c-hanging-comment-ender-p
101 variables to nil. This will be done by the tentative "krb5" style for
104 Spaces go after keywords, but not after function names. Do not,
105 however, put a space after sizeof. Don't put a space after a cast
106 operator, either. Spaces also do not go before parentheses that are
107 argument lists for function calls even if the function call is through
108 a pointer. Spaces go after commas in argument lists, as well as
109 commas that are comma operators. Spaces also go between parts in a
110 for loop, except for "forever" type loops. Use for statements rather
111 than while statements to create forever loops.
114 p = calloc(1024, sizeof(int));
116 cp = (*elem->fp)(1024);
117 for (i = 0; i < 10; i++);
122 Binary operators get spaces, unary ones do not. Prefix and postfix
123 operators also do not get spaces. The structure member operators "."
124 and "->" count as postfix operators syntactically, not as binary
127 x = --a + b / c - d++;
130 Put spaces around the "?" and ":" in a conditional expression.
134 In general, do not parenthesize the argument of "return".
136 Coding practices for C
137 ----------------------
139 Assume, for most purposes, working ANSI/ISO C ('89, not '99) support,
140 both for internal use and for applications compiling against Kerberos
141 header files and libraries. Some exceptions are noted below.
143 Do not use assignments as truth values. Rather than this:
146 if ((retval = krb5_foo()))
156 This makes the code easier to read, and also makes it easier to use
157 debuggers. It may be excusable to put assignments into the
158 conditional espression of a "while" statement, though, like:
160 while ((ch = getopt(argc, argv, "abn")) != -1)
163 Using assignments as truth values in conditional expressions may make
164 code particularly impenetrable.
166 There are at least three types of "zero" known to C. These are the
167 integer zero (0), the null pointer constant (NULL), and the character
168 constant zero ('\0'). Yes, these are usually all technically the
169 integer zero. Use them in their correct contexts. (Purists will
170 point out that 0 is a valid null pointer constant; still, do not use 0
171 to specify a null pointer constant. For further unconfusion, read the
172 section on null pointer constants in the C FAQ.) Do not use a lone
173 variable as a truth value unless it's of integer type. Thus:
185 Do not cast uses of NULL unless you're calling a function with a
186 variable number of arguments, in which case you should cast it to to
187 the appropriate pointer type. Likewise, do not cast the return value
188 from malloc() and friends; the prototype should declare them properly
189 as returning a void * and thus shouldn't require an explicit cast.
191 Do not assume that realloc(NULL, size) will do the right thing, or
192 that free(NULL) will do the right thing. ANSI guarantees that it
193 will, but some old libraries (hopefully becoming obsolete) don't.
194 Also, don't assume that malloc(0) will return a non-NULL pointer.
195 Typically, though, the output of malloc(0) will be safe to pass to
196 realloc() and free().
198 In any case, reading the section in the C FAQ on null pointers is
199 highly recommended to remove confusion regarding null pointers in C,
200 since this is a subject of much confusion to even experienced
201 programmers. In particular, if you do not understand why using
202 calloc() to allocate a struct that contains pointer members or why
203 calling memset() to initialize such a struct to all-bytes-zero is
204 wrong, reread that section again. (Note that there are *lots* of
205 examples of code in the krb5 source tree that erroneously calls
206 memset() to zero a struct, and we should fix these somehow
209 Control flow statements that have a single statement as their body
210 should nevertheless have braces around their bodies if the body is
211 more than one line long, especially in the case of stacked multiple
212 if-else clauses; use:
230 which, while legible to the compiler, may confuse human readers and
231 make the code less maintainable, especially if new branches get added
232 to any of the clauses.
234 Also, you should almost never intersperse conditional compilation
235 directives with control flow statements, as some combination of
236 #define'd symbols may result in statements getting eaten by dangling
237 bits of control flow statements. When it is not possible to avoid
238 this questionable practice (you really should rewrite the relevant
239 code section), make use of redundant braces to ensure that a compiler
240 error will result in preference to incorrect runtime behavior (such as
241 inadvertantly providing someone with a root shell).
243 Do not intersperse conditional compilation directives with control
244 flow statements in such a way that confuses emacs cc-mode. Not only
245 does emacs get confused, but the code becomes more difficult to read
246 and maintain. Therefore, avoid code like this:
260 Put comments after conditional compilation directives such as "#else"
261 and "#endif". Make them correspond to the sense of the value that
262 controls the compilation of the section they are closing, i.e.
270 Also, in the case of more complex conditional compilation directives,
271 write the comments like this:
273 #if defined(FOO) || defined(BAR)
275 #else /* !(defined(FOO) || defined(BAR)) */
277 #endif /* !(defined(FOO) || defined(BAR)) */
279 If you are writing a do-while loop that has only one statement in its
280 body, put braces around it anyway, since the while clause may be
281 mistaken for a while loop with an empty body. Don't do this:
295 While it is syntactically correct to call through a function pointer
296 without applying a dereference operator to it, do not write code that
297 does this. It is easier to see that the function call is actually
298 taking place through a function pointer if you write an explicit
299 dereference. However, do not explicitly take the address of a
300 function in order to assign it to a function pointer, since a function
301 name degrades into a pointer. Thus:
308 In general, do not take the address of an array. It does not return a
309 pointer to the first element; it returns a pointer to the array
310 itself. These are often identical when cast to an integral type, but
311 they are inherently of different types themselves. Functions that
312 take array types or pointers to array types as arguments can be
313 particularly trouble-prone.
315 If a function is declared to return a value, do not call "return"
316 without an argument or allow the flow of control to fall off the end
319 Always declare the return type of a function, even if it returns int.
320 Yes, this means declaring main() to return int, since main() is
321 required to return int by the standard. If a function is not supposed
322 to return a value, declare it as returning void rather than omitting
323 the return type, which will default the return type to int.
325 Try to use ANSI C prototype-style function definitions in preference
326 to K&R style definitions. When using K&R style function definitions,
327 declare all the argument types, even those that are int, but beware of
328 any narrow types in the argument list.
330 Do not declare variables in an inner scope, e.g. inside the compound
331 substatement of an if statement, unless the complexity of the code
332 really demands that the variables be declared that way. In such
333 situations, the function could probably stand to be broken up into
334 smaller chunks anyway. Do not declare variables in an inner scope
335 that shadow ones in an outer scope, since this leads to confusion.
336 Also, some debugging environments, such as gdb under Solaris, can't
337 see variables declared in an inner scope, so declaring such variables
338 will make maintenance more difficult as well.
340 Parenthesize expressions that may be confusing, particularly where C's
341 precedences are broken. For example, the shift operators have lower
342 precedence than the +, -, *, /, and % operators. Perhaps the most
343 familiar C precedence quirk is that equality and relational operators
344 are of higher precedence than assignment operators. Less well known
345 is that the bitwise operators are of a lower precedence than equality
346 and relational operators.
348 The sizeof operator takes either a unary expression or a parenthesized
349 type name. It is not necessary to parenthesize the operand of sizeof
350 if it is applied to a unary expression, but still, always parenthesize
351 the operand of the sizeof operator. The sizeof operator does not
352 evaluate its operand if it is a unary expression, so usages such as
356 should be avoided for the sake of sanity and readability.
358 Don't pass around structures except by address. We may relax this
359 restriction for non-API function, though.
361 For new functions, input parameters should go before output parameters
362 in the call signature. There are exceptions, such as a context-like
365 Every function should have block comment preceding it describing
366 briefly in complete sentences what it does, what inputs and outputs it
367 has, and what error codes it can return. It should also describe any
368 unsual aspects of the function. At some point we will want to put
369 some of this information into a machine-parsable form.
371 Macros should have all-uppercase names. If it is necessary to use
372 multiple statements, use braces, and wrap the whole thing in a
373 do-while(0) construct, such as
375 #define FOOMACRO(x, y) do { \
380 Leave off the semicolon at the end of a function-like macro, so that
381 it can be mostly used like a call to a function without a return
382 value. Line up the backslashes to make it more readable. Use M-x
383 c-backslash-region in emacs to do neat lined-up backslashes.
384 Parenthesize uses of arguments in the replacement text of a macro in
385 order to prevent weird interactions.
387 Strive to make your code capable of compiling using "gcc -Wall
388 -Wmissing-prototypes -Wtraditional -Wcast-qual -Wcast-align
389 -Wconversion -Waggregate-return -pedantic" [XXX need to rethink this
390 somewhat] without generating any errors or warnings. Do not, however,
391 compile using the "-ansi" flag to gcc, since that can result in odd
392 behavior with header files on some systems, causing some necessary
393 symbols to not be defined.
398 The C standard reserves a bunch of namespaces for the implementation.
399 Don't stomp on them. For practical purposes, any identifier with a
400 leading underscore should not be used. (Technically, ^_[a-z].* are
401 reserved only for file scope, so should be safe for things smaller
402 than file scope, but it's better to be paranoid in this case.)
404 POSIX reserves typedef names ending with _t as well.
406 Recall that errno is a reserved identifier, and is permitted to be a
407 macro. Therefore, do not use errno as the name of a structure member,
410 Reserved namespaces are somewhat more restricted than this; read the
411 appropriate section of the C standard if you have questions.
413 If you're writing new library code, pick a short prefix and stick with
414 it for any identifier with external linkage. If for some reason a
415 library needs to have external symbols that should not be visible to
416 the application, pick another (related) prefix to use for the internal
417 globals. This applies to typedef names, tag names, and preprocessor
420 For the krb5 library, the prefix for public global symbols is "krb5_".
421 Use "krb5int_" as a prefix for library internal globals. Avoid using
422 "__" in symbol names, as it may confuse C++ implementations. There
423 are admittedly a number of places where we leak thing into the
424 namespace; we should try to fix these.
426 Header files should also not leak symbols. Usually using the upcased
427 version of the prefix you've picked will suffice, e.g. "KRB5_" as a
428 CPP symbol prefix corresponding to "krb5_". In general, do not define
429 macros that are lowercase, in order to avoid confusion and to prevent
430 namespace collisions.
432 The C standard only guarantees six case-insensitive characters to be
433 significant in external identifiers; this is largely regarded as
434 obsolescent even in 1989 and we will ignore it. It does, however,
435 only guarantee 31 case-sensitive characters to be signficant in
436 internal identifiers, so do not use identifiers that differ beyond the
437 31st character. This is unlikely to be a problem, though.
439 Aspects of C style in GNU coding std but not here
440 -------------------------------------------------
442 * redundant parens to force extra indent of operators of different
445 * redundant parens to force general extra indent of expressions that
446 are broken between lines
448 * use of ^L characters to break up source files into pages
450 * nitpicking about capitalization in comments of variable names when
451 their values are meant
453 * commenting usages of static variables
457 * separation of word in names with underscores vs case change
459 * enum vs #define'd integer constants
461 * 14 char filename limits, MS-DOS filename limits
465 * system library function quirks
467 * internationalization
471 Aspects of C style in BSD KNF but not here
472 ------------------------------------------
474 * sorting of header files
476 * sorting of struct members
478 * separating struct tag decl and struct typedef
480 * sorting of var decl
482 * lining up var names in decls
484 * newline after decls
490 * not initializing vars in decls
492 * stdarg/varargs handling
497 Putting the following code in your .emacs file will result in mostly
498 the right thing happening with respect to formatting style. Note that
499 you may want to turn on auto-newline feature of cc-mode, though that
500 seems to have some bugs with brace-elseif-brace handling at least in
501 the version of cc-mode that comes with emacs 20.3.
503 (defconst krb5-c-style
506 brace-elseif-brace brace-else-brace defun-close-semi)
507 (c-comment-continuation-stars . "* ")
508 (c-electric-pound-behavior alignleft)
509 (c-hanging-braces-alist
512 (substatement-open after)
513 (block-close . c-snug-do-while)
514 (extern-lang-open after))
515 (c-hanging-colons-alist
518 (c-hanging-comment-starter-p)
519 (c-hanging-comment-ender-p)
520 (c-indent-comments-syntactically-p . t)
521 (c-label-minimum-indentation . 0)
522 (c-special-indent-hook)))
523 (defun krb5-c-hook ()
524 (c-add-style "krb5" krb5-c-style t))
525 (add-hook 'c-mode-common-hook 'krb5-c-hook)
530 The following settings for the indent program should produce a
531 reasonable approximation to the C coding style described here, though
532 some manual cleanup may be necessary. Note that the gindent installed
533 in the gnu locker does not currently handle -psl correctly though.
558 [XXX needs to be written]
563 [XXX needs to be written]