--- /dev/null
+WRITING C CODE
+==============
+
+The code in the krb5 source tree largely follows BSD KNF
+(/usr/share/misc/style on NetBSD) except that it uses a four column
+basic offset. The style described here is a synthesis of BSD KNF and
+the GNU coding standards for the C language. The formatting described
+in the "Formatting Your Source Code" section of the GNU coding
+standards is mostly what we want, except we use BSD brace style and
+BSD-ish conventions for the spacing around operators.
+
+Formatting style for C code
+---------------------------
+
+In general, use a four column basic offset, tab stops at eight
+columns. Indents should be tabified, i.e. continuous tabs followed by
+spaces if necessary if the indent isn't a multiple of eight columns.
+The "bsd" style in emacs cc-mode mostly does the right thing. You can
+use "M-x c-set-style" "bsd" to get this. Alternatively, you can use
+the "krb5" style that is included here.
+
+Labels, including case labels, are outdented by four columns.
+Continuations of statements are indented by an additional four
+columns. Continuations of argument lists or parenthesized expressions
+should line up with the column after the opening parenthesis.
+
+The maximum width should be 79 columns. If you need more than this,
+consider rewriting the code so that it fits in 79 columns, since
+control flow that is nested deeply enough to require excessive width
+is also likely to be difficult to understand if not broken up.
+Exceptions may be made for long strings, though ANSI C string
+concatenation should work around that as well.
+
+Function names for definitions should start on column zero, on the
+line following their return type name, e.g.
+
+ char *
+ foo(int a)
+ {
+ /* ... */
+ }
+
+[just pretend that's really at column zero]
+
+The opening brace of a function definition should also be on column
+zero.
+
+Braces that open substatements, such as those following "if", "else",
+"while", "for", "do", and "switch", should be on the same line as the
+begining of the statement. This is sometimes called "hanging" braces.
+The corresponding closing brace should be at the same indentation
+level as the beginning of the statement.
+
+The "while" keyword in a do-while construct should sit on the same
+line as the closing brace of the substatement following "do":
+
+ do {
+ foo();
+ } while (0);
+
+If there is an "if" statement immediately following an "else" keyword,
+it should go on the same line immediately after the "else":
+
+ if (x) {
+ foo();
+ } else if (y) {
+ bar();
+ }
+
+Comments to the right of code start in column 32. Comments not to the
+right of code are indented at the prevailing indent for the
+surrounding code. Make the comments complete sentences. If you need
+more than one line, make them into block comments, like this:
+
+ /*
+ * This is a block comment. It should consist of complete
+ * sentences.
+ *
+ * Paragraphs should be separated by blank lines so that emacs
+ * fill commands will work properly.
+ */
+
+Really important single-line comments should also be done in block
+form:
+
+ /*
+ * This is a really important one-line comment.
+ */
+
+In order to get the start and end delimiters for block comments to
+stay when you use emacs to fill paragraphs in the comments, set both
+the c-hanging-comment-starter-p and the c-hanging-comment-ender-p
+variables to nil. This will be done by the tentative "krb5" style for
+the emacs cc-mode.
+
+Spaces go after keywords, but not after function names. Do not,
+however, put a space after sizeof if its argument is
+parenthesized. [XXX from BSD KNF but do we want to do this?] Don't
+put a space after a cast operator, either. Spaces also do not go
+before parentheses that are argument lists for function calls if there
+is a function pointer being dereferenced somewhere. Spaces go after
+commas in argument lists, as well as commas that are comma operators.
+Spaces also go between parts in a for loop, except for "forever" type
+loops. Use for statements rather than while statements to create
+forever loops.
+
+ if (x) {
+ p = calloc(1024, sizeof(int));
+ }
+ cp = (elem->fp)(1024);
+ for (i = 0; i < 10; i++);
+ for (;;) {
+ /* ... */
+ }
+
+Binary operators get spaces, unary ones do not. Prefix and postfix
+operators also do not get spaces.
+
+ x = --a + b / c - d++;
+ y = p->z.v[x];
+
+In general, do not parenthesize the argument of "return".
+
+Coding practices for C
+----------------------
+
+Do not use assignments as truth values. Rather than this:
+
+ /* bad style */
+ if ((retval = krb5_foo()))
+ /* ... */;
+
+do this:
+
+ retval = krb5_foo();
+ if (retval)
+ /* ... */;
+
+This makes the code easier to read, and also makes it easier to use
+debuggers. It may be excusable to put assignments into the
+conditional espression of a "while" statement, though, like:
+
+ while ((ch = getopt(argc, argv, "abn")) != -1)
+ /* ... */;
+
+Using assignments as truth values in conditional expressions may make
+code particularly impenetrable.
+
+There are at least three types of "zero" known to C. These are the
+integer zero (0), the null pointer constant (NULL), and the character
+constant zero ('\0'). Use them in their correct contexts. (Purists
+will point out that 0 is a valid null pointer constant; still, do not
+use 0 to specify a null pointer constant. For further unconfusion,
+read the section on null pointer constants in the C FAQ.) Do not use
+a lone variable as a truth value unless it's of integer type. Thus:
+
+ int i;
+ char *cp;
+ /* ... */
+ if (i)
+ /* ... */;
+ if (cp != NULL) {
+ while (*cp != '\0')
+ /* ... */;
+ }
+
+Do not cast uses of NULL unless you're calling a function with a
+variable number of arguments, in which case you should cast it to to
+the appropriate pointer type. Likewise, do not cast the return value
+from malloc() and friends; the prototype should declare them properly
+as returning a void * and thus shouldn't require an explicit cast.
+
+Control flow statements that have a single statement as their body
+should nevertheless have braces around ther bodies if the body is more
+than one line long, especially in the case of stacked multiple if-else
+clauses; use:
+
+ /* bad style */
+ if (x) {
+ if (y)
+ foo();
+ else
+ bar();
+ }
+
+instead of:
+
+ if (x)
+ if (y)
+ foo();
+ else
+ bar();
+
+which, while legible to the compiler, may confuse human readers and
+make the code less maintainable. Also, you should almost never
+intersperse conditional compilation directives with control flow
+statements, as some combination of #define'd symbols may result in
+statements getting eaten by dangling bits of control flow statements.
+When it is not possible to avoid this questionable practice (you
+really should rewrite the relevant code section), make use of
+redundant braces to ensure that a compiler error will result in
+preference to incorrect runtime behavior (such as inadvertantly
+providing someone with a root shell). Also, do not intersperse
+conditional compilation directives with control flow statements in
+such a way that confuses emacs cc-mode. Not only does emacs get
+confused, but the code becomes more difficult to read and
+maintain. Therefore, avoid code like this:
+
+ /* bad style */
+ if (x) {
+ f();
+ }
+ #ifdef FOO
+ else if (y) {
+ #else
+ else {
+ #endif
+ g();
+ }
+
+If a function is declared to return a value, do not call "return"
+without an argument or allow the flow of control to fall off the end
+of the function.
+
+Do not declare variables in an inner scope, e.g. inside a compound
+substatement of an if statement, unless the complexity of the code
+really demands that the variables be declared that way. In such
+situations, the function could probably stand to be broken up into
+smaller chunks anyway. Do not declare variables in an inner scope
+that shadow ones in an outer scope, since this leads to confusion.
+Also, some debugging environments, such as gdb under Solaris, can't
+see variables declared in an inner scope, so declaring such variables
+will make maintenance more difficult as well.
+
+Parenthesize expressions that may be confusing, particularly where C's
+precedences are broken. For example, the shift operators have lower
+precedence than the +, -, *, /, and % operators. Perhaps the most
+familiar C precedence quirk is that equality and relational operators
+are of higher precedence than assignment operators. Less well known
+is that the bitwise operators are of a lower precedence than equality
+and relational operators.
+
+Strive to make your code capable of compiling using "gcc -Wall
+-Wmissing-prototypes -Wtraditional -Wcast-qual -Wcast-align
+-Wconversion -Waggregate-return -pedantic" [XXX need to rethink this
+somewhat] without generating any errors or warnings. Do not, however,
+compile using the "-ansi" flag to gcc, since that can result in odd
+behavior with header files on some systems, causing some necessary
+symbols to not be defined.
+
+Emacs cc-mode style
+-------------------
+
+Putting the following code in your .emacs file will result in mostly
+the right thing happening with respect to formatting style. Note that
+you may want to turn on auto-newline feature of cc-mode, though that
+seems to have some bugs with brace-elseif-brace handling at least in
+the version of cc-mode that comes with emacs 20.3.
+
+ (defconst krb5-c-style
+ '("bsd"
+ (c-cleanup-list
+ brace-elseif-brace brace-else-brace defun-close-semi)
+ (c-comment-continuation-stars . "* ")
+ (c-electric-pound-behavior alignleft)
+ (c-hanging-braces-alist
+ (brace-list-open)
+ (class-open after)
+ (substatement-open after)
+ (block-close . c-snug-do-while)
+ (extern-lang-open after))
+ (c-hanging-colons-alist
+ (case-label after)
+ (label after))
+ (c-hanging-comment-starter-p)
+ (c-hanging-comment-ender-p)
+ (c-indent-comments-syntactically-p . t)
+ (c-label-minimum-indentation . 0)
+ (c-special-indent-hook)))
+ (defun krb5-c-hook ()
+ (c-add-style "krb5" krb5-c-style t))
+ (add-hook 'c-mode-common-hook 'krb5-c-hook)
+
+indent.pro settings
+-------------------
+
+The following settings for the indent program should produce a
+reasonable approximation to the C coding style described here, though
+some manual cleanup may be necessary. Note that the gindent installed
+in the gnu locker does not currently handle -psl correctly though.
+
+-bap
+-br
+-ce
+-ci4
+-cli0
+-d0
+-di8
+-i4
+-ip
+-l79
+-nbc
+-ncdb
+-ndj
+-nfc1
+-lp
+-npcs
+-psl
+-sc
+-sob
projects / krb5.git / commitdiff