15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H2>C Language</H2>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariAn ANSI standard C compiler and library are assumed. Feel free to use any

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariANSI C feature.<P>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H2>Warnings</H2>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariGiven a reasonable set of things to warn about (e.g. -W -Wall for gcc), the

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarigoal is to compile with no warnings.

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H2>C Source Code</H2>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<H3>Copyright</H3>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariAll source files should have a copyright. The copyright year(s)

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarishould be kept current. The files and the copyright year(s) should be

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarilisted in util/copyrights.<P>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H3>Line Formatting</H3>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<H4>Indentation</H4>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariUse tabs. Spaces are only allowed when needed to line up a continued

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegariexpression. In the following example, spaces used for indentation are

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegariindicated with "_":

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari printf("this is going to be %s very long %s statement\n",

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari _______"a", "printf");

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari</CODE></PRE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H4>Vertical Whitespace</H4>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariVertical whitespace is also encouraged for improved code legibility by

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegarigrouping closely related statements and then separating them with a

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarisingle empty line. There should not, however, be more than one empty

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegariadjacent line anywhere.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<H4>Line Length</H4>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariLines should not be longer than 79 characters, even if it requires

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegariviolating the indentation rules to do so. Since ANSI is assumed, the

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegaribest way to deal with strings that extend past column 79 is to break

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarithem into two or more sections separated from each other by a newline

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegariand indentation:

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari puts("This string got very far to the "

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari "left and wrapped. ANSI catenation "

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari "rules will turn this into one

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari "long string.");

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari</CODE></PRE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<H3>Comments</H3>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariComments should be used anytime they improve the readability of the code.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariComments may be single-line or multiline. A single-line comment should be

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegariat the end of the line if there is other text on the line, and should start

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegariin the same column as other nearby end-of-line comments. The comment

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarishould be at the same indentation level as the text it is referring to.

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariMultiline comments should start with "/*" on a line by itself. Subsequent

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarilines should have " *" lined-up with the "*" above. The end of the comment

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarishould be " */" on a line by itself, again with the "*" lined-up with the

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarione above. Comments should start with a capital letter and end with a

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariperiod.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariGood:<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari /*

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari * Private variables.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari static int a /* Description of 'a'. */

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari static int b /* Description of 'b'. */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari static char * c /* Description of 'c'. */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari</CODE></PRE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariThe following lint and lint-like comments should be used where appropriate:

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<PRE><CODE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari /* ARGSUSED */

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari /* FALLTHROUGH */

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari /* NOTREACHED */

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari /* VARARGS */

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari</CODE></PRE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<H3>.h files</H3>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari.h files should not rely on other files having been included. .h

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarifiles should prevent multiple inclusion. The OS is assumed to prevent

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarimultiple inclusion of its .h files.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari.h files that define modules should have a structure like the

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarifollowing. Note that <isc/lang.h> should be included by any public

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariheader file to get the ISC_LANG_BEGINDECLS and ISC_LANG_ENDDECLS

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarimacros used so the correct name-mangling happens for function

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarideclarations when C++ programs include the file. <isc/lang.h> should

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaribe included for private header files or for public files that do not

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarideclare any functions.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari/*

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * Copyright (C) 1998 Internet Software Consortium.

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * Permission to use, copy, modify, and distribute this software for any

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari * purpose with or without fee is hereby granted, provided that the above

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * copyright notice and this permission notice appear in all copies.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * SOFTWARE.

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari */

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari#ifndef ISC_WHATEVER_H

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari#define ISC_WHATEVER_H 1

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari/*****

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari ***** Module Info

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *****/

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari/*

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * (Module name here.)

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * (One line description here.)

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * (Extended description and notes here.)

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * MP:

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * (Information about multiprocessing considerations here, e.g. locking

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari * requirements.)

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * Reliability:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * (Any reliability concerns should be mentioned here.)

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari *

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari * Resources:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * (A rough guide to how resources are used by this module.)

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * Security:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * (Any security issues are discussed here.)

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * Standards:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * (Any standards relevant to the module are listed here.)

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/***

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *** Imports

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari ***/

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/* #includes here. */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari#include &lt;isc/lang.h&gt;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/***

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *** Types

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari ***/

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/* (Type definitions here.) */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/***

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari *** Functions

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari ***/

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariISC_LANG_BEGINDECLS

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari/* (Function declarations here, with full prototypes.) */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariISC_LANG_ENDDECLS

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari#endif /* ISC_WHATEVER_H */

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari</CODE></PRE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<H3>C Source</H3>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<H4>Including Interfaces (.h files)</H4>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariThe first file to be included in a C source file must be config.h.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariThe config.h file must never be included by any public header file

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari(that is, any header file that will be installed by "make install").

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariTry to include only necessary files, not everything under the sun.<P>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariOperating-system-specific files should not be included by most modules.<P>

15042bad71a157e77c0a1893759f9027b2673a1eDaniel CalegariInclude UNIX "sys" .h files before ordinary C includes.<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<H4>Statements</H4>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariThere should be at most one statement per line. The comma operator

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarishould not be used to form compound statements.<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariBad:<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<PRE><CODE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari if (i > 0) {

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari printf("yes\n"); i = 0; j = 0;

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari x = 4, y *= 2;

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari }

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari</CODE></PRE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<H4>Functions</H4>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariThe use of ANSI C function prototypes is required.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariThe return type of the function should be listed on a line by itself when

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarispecifying the implementation of the function. The opening curly brace should

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarioccur on the same line as the argument list, unless the argument list is

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarimore than one line long.<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariGood:<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegaristatic inline void

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarif(int i) {

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari /* whatever */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari}

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariint

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarig(int i, /* other args here */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari int last_argument)

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari{

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari return (i * i);

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari}

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari</CODE></PRE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariTo suppress compiler warnings, unused function arguments are declared

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegariusing the <CODE>UNUSED()</CODE> macro.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariIn the function body, local variable declarations are followed by any

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<CODE>REQUIRE()</CODE>s, <CODE>UNUSED()</CODE> declarations, and other

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaricode, in this order. These sections are separated by blank lines.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<H4>Curly Braces</H4>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariCurly Braces do not get their own indentation.

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariAn opening brace does not start a new line. The statements enclosed

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariby the braces should not be on the same line as the opening or closing

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegaribrace. A closing brace should be the only thing on the line, unless

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariit's part of an else clause.<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari

4c12187acb198e833aea3a634c4c259629c71a6dDaniel CalegariGenerally speaking, when a control statement (<CODE>if, for</CODE> or

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<CODE>while</CODE>) has only a single action associated with it, then no

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaribracing is used around the statement. Exceptions include when the

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaricompiler would complain about an ambiguous else clause, or when extra

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaribracing improves the readability (a judgement call biased toward not

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarihaving the braces).<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariGood:<P>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari<PRE><CODE>

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegaristatic void

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegarif(int i) {

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari if (i > 0) {

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari printf("yes\n");

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari i = 0;

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari } else

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari printf("no\n");

4c12187acb198e833aea3a634c4c259629c71a6dDaniel Calegari}

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari</CODE></PRE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel CalegariBad:<P>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<PRE><CODE>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegarivoid f(int i)

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari {

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari if(i<0){i=0;printf("was negative\n");}

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari if (i > 0)

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari {

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari printf("yes\n");

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari i = 0;

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari }}

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari</CODE></PRE>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<H4>Spaces</H4>

76865b54ad4551e3956595cdbdcba9afe78c26adDaniel Calegari<UL>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do put a space between operators like '=', '+', '==', etc.

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<LI>Do put a space after ','.

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<LI>Do put a space after ';' in a 'for' statement.

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari<LI>Do put a space after 'return', and also parenthesize the return value.

15042bad71a157e77c0a1893759f9027b2673a1eDaniel Calegari</UL>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<UL>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space between a variable or function name and '(' or '['.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space after the "sizeof" operator name, and also

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariparenthesize its argument, as in <CODE>malloc(4 * sizeof(long))</CODE>.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space immediately after a '(' or immediately before a ')',

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariunless it improves readability. The same goes for '[' and ']'.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space before '++' or '--' when used in

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaripost-increment/decrement mode, or after them when used in

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel Calegaripre-increment/decrement mode.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space before ';' when terminating a statement or in a 'for'

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaristatement.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space after '*' when used to dereference a pointer, or on

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarieither side of '->'.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space after '~'.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>The '|' operator may either have a space on both sides or it may have no

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarispaces.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<LI>Do not put a space after a cast.

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel Calegari</UL>

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel Calegari

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel Calegari<H4>Return Values</H4>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariIf a function returns a value, it should be cast to (void) if you don't

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaricare what the value is, except for <CODE>printf</CODE> and its variants,

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<CODE>fputc</CODE>, <CODE>fwrite</CODE> (when writing text),

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<CODE>fflush</CODE>,

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<CODE>memcpy</CODE>, <CODE>memmove</CODE>, <CODE>memset</CODE>,

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<CODE>strcpy</CODE>, <CODE>strncpy</CODE>, and <CODE>strcat</CODE>.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<P>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariCertain functions return values or not depending on the operating

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarisystem or even compiler flags; these include

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarithese include <CODE>openlog</CODE> and <CODE>srandom</CODE>.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariThe return value of these should not be used nor cast to (void).

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<P>

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel Calegari

9f226cec9f978edaba67aee4c4e04e3d3b994b87Daniel CalegariAll error conditions must be handled.<P>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariMixing of error status and valid results within a single type should be

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegariavoided.<P>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariGood:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<PRE><CODE>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari os_descriptor_t s;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari os_result_t result;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari result = os_socket_create(AF_INET, SOCK_STREAM, 0, &s);

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari if (result != OS_R_SUCCESS) {

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari /* Do something about the error. */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari return;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari }

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari</CODE></PRE>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariNot so good:

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<PRE><CODE>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari int s;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari /*

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * Obviously using interfaces like socket() (below) is allowed

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * since otherwise you couldn't call operating system routines; the

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari * point is not to write more interfaces like them.

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari s = socket(AF_INET, SOCK_STREAM, 0);

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari if (s < 0) {

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari /* Do something about the error using errno. */

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari return;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari }

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari</CODE></PRE>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<H4>Integral Types</H4>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariCareful thought should be given to whether an integral type should be

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarisigned or unsigned, and to whether a specific size is required. "int"

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarishould be used for generic variables (e.g. iteration counters, array

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarisubscripts). Other than for generic variables, if a negative value isn't

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarimeaningful, the variable should be unsigned. Assignments and

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegaricomparisons between signed and unsigned integers should be avoided;

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarisuppressing the warnings with casts is not desireable.<P>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari<H4>Casting</H4>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel CalegariCasting should be avoided when possible. When it is necessary, there

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegarishould be no space between the cast and what is being cast.<P>

100ddc17625c25a9ffe83737edc53db7538b41ffDaniel Calegari

Bad (obviously for more than one reason ...):

<PRE><CODE>

(void) malloc(SMBUF);

</CODE></PRE>

<H4>Clear Success or Failure</H4>

A function should report success or failure, and do so accurately. It

should never fail silently. Use of Design by Contract can help here.<P>

When a function is designed to return results to the caller by

assigning to caller variables through pointer arguments, it should

perform the assignment only if it succeeds and leave the variables

unmodified if it fails.<P>

<H4>Testing Bits</H4>

Bit testing should be as follows:<P>

Good:

<PRE><CODE>

/* Test if flag set. */

if ((flags & FOO) != 0) {

}

/* Test if flag clear. */

if ((flags & BAR) == 0) {

}

/* Test if both flags set. */

if ((flags & (FOO|BAR)) == (FOO|BAR)) {

}

</CODE></PRE>

Bad:

<PRE><CODE>

/* Test if flag set. */

if (flags & FOO) {

}

/* Test if flag clear. */

if (! (flags & BAR)) {

}

</CODE></PRE>

<H4>Pointers</H4>

<H5>Null Pointer</H5>

The null pointer value should be referred to with "NULL", not with "0".

Testing to see whether a pointer is NULL should be explicit.<P>

Good:

<PRE><CODE>

char *c = NULL;

/* ... */

if (c == NULL) {

/* Do something. */

}

</CODE></PRE>

<H5>Invalidating Pointers</H5>

When the data a pointer points to has been freed, or is otherwise no longer

valid, the pointer should be set to NULL unless the pointer is part of a

structure which is itself going to be freed immediately.<P>

Good:

<PRE><CODE>

char *text;

/* text is initialized here. */

free(text);

text = NULL;

</CODE></PRE>

<H4>Testing for Zero or Non-zero</H4>

Explicit testing against zero is required for numeric, non-boolean variables.

<P>

Good:

<PRE><CODE>

int i = 10;

/* ... */

if (i != 0) {

/* Do something. */

}

</CODE></PRE>

Bad:

<PRE><CODE>

int i = 10;

/* ... */

if (i) {

/* Do something. */

}

</CODE></PRE>

<H4>The Ternary Operator</H4>

The ?: operator should mostly be avoided. It is tolerated when

deciding what value to pass as a parameter to a function, such as

frequently happens with printf, and also when a simple (non-compound)

value is being used in assignment or as part of a calculation.

In particular, using the ternary operator to specify a return value is

verboten.<P>

Good:

<PRE><CODE>

printf("%c is%s a number.\n", c, isdigit(c) ? "" " NOT");

l = (l1 < l2) ? l1 : l2;

if (gp.length + (go < 16384 ? 2 : 3) >= name->length) {

...

}

</CODE></PRE>

Bad:

<PRE><CODE>

return (success ? ISC_R_SUCESS : ISC_R_FAILURE);

</CODE></PRE>

<H4>Assignment in Parameters</H4>

Variables should not have their values assigned or changed when being

passed as parameters, except perhaps for the increment and decrement

operators.<P>

Bad:

<PRE><CODE>

malloc(size = 20);

</CODE></PRE>

Ok:

<PRE><CODE>

fputc(c++, stdout);

</CODE></PRE>

<H3>Namespace</H3>

<H4>Public Interfaces</H4>

All public interfaces to functions, macros, typedefs, and

variables provided by the library, should use names of the form

{library}_{module}_{what}, such as:

<PRE><CODE>

isc_buffer_t /* typedef */

dns_name_setbuffer(name, buffer) /* function */

ISC_LIST_HEAD(list) /* macro */

isc_commandline_argument /* variable */

</CODE></PRE>

however, structures which are typedef'd generally have the name of the

typedef sans the final _t:

<PRE><CODE>

struct dns_rbtnode {

/* ... members ... */

}

</CODE></PRE>

Generally speaking macros are defined with all capital letters, but

this is not universally consistent (eg, numerous isc_buffer_{foo}

macros).<P>

The {module} and {what} segments of the name do not have underscores

separating natural word elements, as demonstrated in

isc_commandline_argument and dns_name_setbuffer above. The {module}

part is usually the same as the basename of the source file, but

sometimes other {module} interfaces appear within one file, such as

dns_label_* interfaces in lib/dns/name.c. However, in the public

libraries the file name must be the same as some module interface

provided by the file; e.g., dns_rbt_* interfaces would not be declared

in a file named redblack.c (in lieu of any other dns_redblack_*

interfaces in the file).<P>

The one notable exception to this naming rule is the interfaces

provided by <isc/util.h>. There's a large caveat associated with the

public description of this file that it is hazardous to use because it

pollutes the general namespace.<P>

<H4>Shared Private Interfaces</H4>

When a module provides an interface for internal use by other modules

in the library, it should use the same naming convention

described for the public interfaces, except {library} and {module}

are separated by a double-underscore. This indicates that the name is

internal, its API is not as formal as the public API, and thus it

might change without any sort of notice.

<H3>Initialization</H3>

When an object is allocated from the heap, all fields in the object must be

initialized.<P>

<H3>Dead Code Pruning</H3>

Source which becomes obsolete should be removed, not just disabled with

#if 0 ... #endif.<P>

<H3>Log messages</H3>

Error and warning messages should be logged through the logging

system. Debugging printfs may be used during development, but

must be removed when the debugging is finished. The

<CODE>UNEXPECTED_ERROR()</CODE> macro is obsolete and

should not be used in new code.<P>

Log messages do not start with a capital letter, nor do they end

in a period.<P>

When variable text such as a file name or domain name occurs

as part of an English phrase, it should be enclosed in single

quotes, as in <CODE>"zone '%s' is lame"</CODE>.<P>

When the variable text forms a separate phrase, such as when it

separated from the rest of the message by a colon, it can be left

unquoted. E.g., <CODE>isc_log_write(... "open: %s: %s", filename,

isc_result_totext(result));</CODE><P>

Function names, line numbers, memory addresses, and other references

to program internals may be used in debugging messages and in

messages to report programming errors detected at runtime.

They may not be used in messages that indicate errors in the

program's inputs or operation.<P>

<H2>Perl source code</H2>

Perl must not be required for building, installing, or using the BIND 9

name server. It may be used for things like test scripts and optional

server add-on components.<P>

Perl 5 is assumed; Perl scripts do not need to work in Perl 4.<P>

Perl source code should follow the conventions for C source code

where applicable.<P>