coding.html revision c6dfea8665a97e14a970f188060a81a46fd6d31c
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyAn ANSI standard C compiler and library are assumed. Feel free to use any
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyANSI C feature.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyGiven a reasonable set of things to warn about (e.g. -W -Wall for gcc), the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleygoal is to compile with no warnings.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyAll source files should have a copyright. The copyright year(s)
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyshould be kept current. The files and the copyright year(s) should be
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyUse tabs. Spaces are only allowed when needed to line up a continued
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyexpression. In the following example, spaces used for indentation are
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyindicated with "_":
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley printf("this is going to be %s very long %s statement\n",
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley _______"a", "printf");
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<H4>Line Length</H4> Lines should not be longer than 80 characters,
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyeven if it requires violating the indentation rules to do so.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyComments should be used anytime they improve the readability of the code.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyComments may be single-line or multiline. A single-line comment should be
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyat the end of the line of there is other text on the line, and should start
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyin the same column as other nearby end-of-line comments. The comment
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyshould be at the same indentation level as the text it is referring to.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyMultiline comments should start with "/*" on a line by itself. Subsequent
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleylines should have " *" lined-up with the "*" above. The end of the comment
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyshould be " */" on a line by itself, again with the "*" lined-up with the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyone above. Comments should start with a capital letter and end with a
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Private variables.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley static int a /* Description of 'a'. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley static int b /* Description of 'b'. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley static char * c /* Description of 'c'. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe following lint and lint-like comments should be used where appropriate:
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* ARGSUSED */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* FALLTHROUGH */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* NOTREACHED */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* VARARGS */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley.h files should not rely on other files having been included. .h
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyfiles should prevent multiple inclusion. The OS is assumed to prevent
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleymultiple inclusion of its .h files.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley.h files that define modules should have a structure like the following:<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Copyright (C) 1998 Internet Software Consortium.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Permission to use, copy, modify, and distribute this software for any
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * purpose with or without fee is hereby granted, provided that the above
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * copyright notice and this permission notice appear in all copies.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley#ifndef ISC_WHATEVER_H
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley#define ISC_WHATEVER_H 1
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley ***** Module Info
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * <Information about multiprocessing considerations here, e.g. locking
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * requirements>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Reliability:
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * <Any reliability concerns should be mentioned here>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Resources:
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * <A rough guide to how resources are used by this module>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Standards:
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * <Any standards relevant to the module are listed here>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley *** Functions
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley#endif /* ISC_WHATEVER_H */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe first file to be included must be config.h.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyTry to include only necessary files, not everything under the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyOperating-system-specific files should not be included by most modules.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyInclude UNIX "sys" .h files before ordinary C includes.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThere should be at most one statement per line.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (i > 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley printf("yes\n"); i = 0; j = 0;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe use of ANSI C function prototypes is required.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe return type of the function should be listed on a line by itself when
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyspecifying the implementation of the function. The opening curly brace should
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyoccur on the same line as the argument list, unless the argument list is
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleymore than one line long.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleystatic inline void
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* whatever */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyg(int i, /* other args here */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley int last_argument)
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley return (i * i);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<H4>Curly Braces</H4> Curly Braces do not get their own indentation.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyAn opening brace does not start a new line. The statements enclosed
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyby the braces should not be on the same line as the opening or closing
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleybrace. A closing brace should be the only thing on the line, unless
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyit's part of an else clause.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (i > 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley printf("yes\n");
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley printf("no\n");
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyvoid f(int i)
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley printf("yes\n");
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do put a space between operators like '+', '==', etc.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do put a space after ','.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do put a space after ';' in a 'for' statement.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do put a space after 'return', and also parenthesize the return value.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space between a variable or function name and '(' or '['.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space immediately after a '(' or immediately before a ')',
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyunless it improves readability. The same goes for '[' and ']'.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space before '++' or '--' when used in
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleypost-increment/decrement mode, or after them when used in
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space before ';' when terminating a statement or in a 'for'
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space after '*' when used to dereference a pointer, or on
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyeither side of '->'.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>Do not put a space after '~'.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley<LI>The '|' operator may either have a space on both sides or it may have no
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyIf a function returns a value, it should be cast to (void) if you don't
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleycare what the value is. (Exception for <CODE>printf()</CODE>?)<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyAll error conditions must be handled.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyMixing of error status and valid results within a single type should be
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley os_descriptor_t s;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley os_result_t result;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley result = os_socket_create(AF_INET, SOCK_STREAM, 0, &s);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (result != OS_R_SUCCESS) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Do something about the error. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * Obviously using interfaces like socket() (below) is allowed
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * since otherwise you couldn't call operating system routines; the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley * point is not to write more interfaces like them.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley s = socket(AF_INET, SOCK_STREAM, 0);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (s < 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley</CODE></PRE>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyCareful thought should be given to whether an integral type should be
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleysigned or unsigned, and to whether a specific size is required. "int"
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyshould be used for generic variables (e.g. iteration counters, array
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleysubscripts). Other than for generic variables, if a negative value isn't
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleymeaningful, the variable should be unsigned. Assignments and
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleycomparisons between signed and unsigned integers should be avoided;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleysuppressing the warnings with casts is not desireable.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyCasting should be avoided when possible.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyA function should report success or failure, and do so accurately. It
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyshould never fail silently. Use of Design by Contract can help here.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyBit testing should be as follows:<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Test if flag set. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if ((flags & FOO) != 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Test if flag clear. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if ((flags & BAR) == 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Test if both flags set. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if ((flags & (FOO|BAR)) == (FOO|BAR)) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Test if flag set. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (flags & FOO) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Test if flag clear. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (! (flags & BAR)) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe null pointer value should be referred to with "NULL", not with "0".
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyTesting to see whether a pointer is NULL should be explicit.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley char *c = NULL;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (c == NULL) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Do something. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyWhen the data a pointer points to has been freed, or is otherwise no longer
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyvalid, the pointer should be set to NULL unless the pointer is part of a
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleystructure which is itself going to be freed immediately.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* text is initalized here. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley text = NULL;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyExplicit testing against zero is required for numeric, non-boolean variables.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (i != 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Do something. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Do something. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyWhen an object is allocated from the heap, all fields in the object must be
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyinitialized.<P>
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleySource which becomes obsolete should be removed, not just disabled with
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley#if 0 ... #endif.<P>