-WRITING C CODE
-==============
+Please see
-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.
+ http://k5wiki.kerberos.org/wiki/Coding_style
-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
+for the current coding style.
projects / krb5.git / blobdiff