22N/A

22N/A

22N/A<H2>C Language</H2>

22N/A

259N/AAn ANSI standard C compiler and library are assumed. Feel free to use any

22N/AANSI C feature.<P>

22N/A

55N/A<H2>Warnings</H2>

24N/AGiven a reasonable set of things to warn about (e.g. -W -Wall for gcc), the

22N/Agoal is to compile with no warnings.

22N/A

22N/A<H2>C Source Code</H2>

22N/A

55N/A<H3>Copyright</H3>

22N/A

22N/AAll source files should have a copyright. The copyright year(s)

260N/Ashould be kept current. The files and the copyright year(s) should be

22N/Alisted in util/copyrights.<P>

22N/A

157N/A<H3>Line Formatting</H3>

289N/A<H4>Indentation</H4>

22N/AUse tabs. Spaces are only allowed when needed to line up a continued

49N/Aexpression. In the following example, spaces used for indentation are

289N/Aindicated with "_":

289N/A<PRE><CODE>

289N/A printf("this is going to be %s very long %s statement\n",

289N/A _______"a", "printf");

289N/A</CODE></PRE>

49N/A

22N/A<H4>Vertical Whitespace</H4>

22N/AVertical whitespace is also encouraged for improved code legibility by

23N/Agrouping closely related statements and then separating them with a

23N/Asingle empty line. There should not, however, be more than one empty

23N/Aadjacent line anywhere.

22N/A

22N/A<H4>Line Length</H4>

22N/ALines should not be longer than 79 characters, even if it requires

22N/Aviolating the indentation rules to do so. Since ANSI is assumed, the

22N/Abest way to deal with strings that extend past column 79 is to break

22N/Athem into two or more sections separated from each other by a newline

50N/Aand indentation:

22N/A

24N/A<PRE><CODE>

24N/A puts("This string got very far to the "

24N/A "left and wrapped. ANSI catenation "

22N/A "rules will turn this into one

22N/A "long string.");

50N/A</CODE></PRE>

50N/A

50N/A<H3>Comments</H3>

50N/AComments should be used anytime they improve the readability of the code.<P>

22N/A

22N/AComments may be single-line or multiline. A single-line comment should be

22N/Aat the end of the line if there is other text on the line, and should start

22N/Ain the same column as other nearby end-of-line comments. The comment

24N/Ashould be at the same indentation level as the text it is referring to.

24N/AMultiline comments should start with "/*" on a line by itself. Subsequent

260N/Alines should have " *" lined-up with the "*" above. The end of the comment

22N/Ashould be " */" on a line by itself, again with the "*" lined-up with the

22N/Aone above. Comments should start with a capital letter and end with a

22N/Aperiod.<P>

145N/AGood:<P>

22N/A<PRE><CODE>

22N/A /*

22N/A * Private variables.

22N/A */

22N/A

22N/A static int a /* Description of 'a'. */

24N/A static int b /* Description of 'b'. */

24N/A static char * c /* Description of 'c'. */

32N/A</CODE></PRE>

24N/A

258N/AThe following lint and lint-like comments should be used where appropriate:

258N/A<PRE><CODE>

258N/A /* ARGSUSED */

260N/A /* FALLTHROUGH */

258N/A /* NOTREACHED */

26N/A /* VARARGS */

26N/A</CODE></PRE>

26N/A

26N/A<H3>.h files</H3>

259N/A.h files should not rely on other files having been included. .h

259N/Afiles should prevent multiple inclusion. The OS is assumed to prevent

259N/Amultiple inclusion of its .h files.<P>

113N/A.h files that define modules should have a structure like the

113N/Afollowing. Note that <isc/lang.h> should be included by any public

113N/Aheader file to get the ISC_LANG_BEGINDECLS and ISC_LANG_ENDDECLS

113N/Amacros used so the correct name-mangling happens for function

113N/Adeclarations when C++ programs include the file. <isc/lang.h> should

22N/Abe included for private header files or for public files that do not

22N/Adeclare any functions.<P>

22N/A<PRE><CODE>

22N/A/*

22N/A * Copyright (C) 1998 Internet Software Consortium.

23N/A *

23N/A * Permission to use, copy, modify, and distribute this software for any

22N/A * purpose with or without fee is hereby granted, provided that the above

22N/A * copyright notice and this permission notice appear in all copies.

22N/A *

22N/A * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS

22N/A * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES

260N/A * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE

22N/A * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL

26N/A * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR

26N/A * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS

26N/A * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS

26N/A * SOFTWARE.

26N/A */

26N/A

26N/A#ifndef ISC_WHATEVER_H

26N/A#define ISC_WHATEVER_H 1

26N/A

26N/A/*****

26N/A ***** Module Info

26N/A *****/

26N/A

26N/A/*

26N/A * (Module name here.)

26N/A *

22N/A * (One line description here.)

22N/A *

22N/A * (Extended description and notes here.)

22N/A *

22N/A * MP:

22N/A * (Information about multiprocessing considerations here, e.g. locking

22N/A * requirements.)

22N/A *

22N/A * Reliability:

22N/A * (Any reliability concerns should be mentioned here.)

22N/A *

22N/A * Resources:

22N/A * (A rough guide to how resources are used by this module.)

22N/A *

22N/A * Security:

22N/A * (Any security issues are discussed here.)

22N/A *

22N/A * Standards:

22N/A * (Any standards relevant to the module are listed here.)

37N/A */

22N/A

22N/A/***

22N/A *** Imports

22N/A ***/

22N/A

22N/A/* #includes here. */

22N/A#include &lt;isc/lang.h&gt;

25N/A

22N/A/***

22N/A *** Types

22N/A ***/

260N/A

25N/A/* (Type definitions here.) */

25N/A

22N/A/***

22N/A *** Functions

22N/A ***/

22N/AISC_LANG_BEGINDECLS

22N/A/* (Function declarations here, with full prototypes.) */

22N/AISC_LANG_ENDDECLS

22N/A

22N/A#endif /* ISC_WHATEVER_H */

22N/A

260N/A</CODE></PRE>

22N/A

260N/A<H3>C Source</H3>

22N/A<H4>Including Interfaces (.h files)</H4>

22N/AThe first file to be included in a C source file must be config.h.

145N/AThe config.h file must never be included by any public header file

45N/A(that is, any header file that will be installed by "make install").

45N/ATry to include only necessary files, not everything under the sun.<P>

45N/AOperating-system-specific files should not be included by most modules.<P>

45N/AInclude UNIX "sys" .h files before ordinary C includes.<P>

45N/A

45N/A<H4>Statements</H4>

145N/AThere should be at most one statement per line. The comma operator

145N/Ashould not be used to form compound statements.<P>

145N/ABad:<P>

145N/A<PRE><CODE>

145N/A if (i > 0) {

22N/A printf("yes\n"); i = 0; j = 0;

57N/A x = 4, y *= 2;

57N/A }

57N/A</CODE></PRE>

57N/A<H4>Functions</H4>

57N/AThe use of ANSI C function prototypes is required.<P>

145N/AThe return type of the function should be listed on a line by itself when

137N/Aspecifying the implementation of the function. The opening curly brace should

49N/Aoccur on the same line as the argument list, unless the argument list is

49N/Amore than one line long.<P>

49N/AGood:<P>

49N/A<PRE><CODE>

49N/Astatic inline void

137N/Af(int i) {

49N/A /* whatever */

72N/A}

72N/A

289N/Aint

49N/Ag(int i, /* other args here */

49N/A int last_argument)

50N/A{

50N/A return (i * i);

50N/A}

50N/A</CODE></PRE>

137N/A

137N/ATo suppress compiler warnings, unused function arguments are declared

137N/Ausing the <CODE>UNUSED()</CODE> macro.<P>

49N/A

51N/AIn the function body, local variable declarations are followed by any

51N/A<CODE>REQUIRE()</CODE>s, <CODE>UNUSED()</CODE> declarations, and other

76N/Acode, in this order. These sections are separated by blank lines.<P>

76N/A

76N/A<H4>Curly Braces</H4>

289N/ACurly Braces do not get their own indentation.

76N/AAn opening brace does not start a new line. The statements enclosed

76N/Aby the braces should not be on the same line as the opening or closing

76N/Abrace. A closing brace should be the only thing on the line, unless

76N/Ait's part of an else clause.<P>

76N/A

76N/AGenerally speaking, when a control statement (<CODE>if, for</CODE> or

76N/A<CODE>while</CODE>) has only a single action associated with it, then no

76N/Abracing is used around the statement. Exceptions include when the

76N/Acompiler would complain about an ambiguous else clause, or when extra

78N/Abracing improves the readability (a judgement call biased toward not

76N/Ahaving the braces).<P>

49N/A

49N/AGood:<P>

51N/A<PRE><CODE>

76N/Astatic void

49N/Af(int i) {

49N/A if (i > 0) {

49N/A printf("yes\n");

49N/A i = 0;

22N/A } else

49N/A printf("no\n");

49N/A}

78N/A</CODE></PRE>

49N/ABad:<P>

45N/A<PRE><CODE>

49N/Avoid f(int i)

49N/A {

76N/A if(i<0){i=0;printf("was negative\n");}

45N/A if (i > 0)

76N/A {

51N/A printf("yes\n");

76N/A i = 0;

24N/A }}

55N/A</CODE></PRE>

260N/A

55N/A<H4>Spaces</H4>

55N/A<UL>

55N/A<LI>Do put a space between operators like '=', '+', '==', etc.

55N/A<LI>Do put a space after ','.

55N/A<LI>Do put a space after ';' in a 'for' statement.

55N/A<LI>Do put a space after 'return', and also parenthesize the return value.

27N/A</UL>

22N/A<UL>

22N/A<LI>Do not put a space between a variable or function name and '(' or '['.

22N/A<LI>Do not put a space after the "sizeof" operator name, and also

22N/Aparenthesize its argument, as in <CODE>malloc(4 * sizeof(long))</CODE>.

22N/A<LI>Do not put a space immediately after a '(' or immediately before a ')',

22N/Aunless it improves readability. The same goes for '[' and ']'.

22N/A<LI>Do not put a space before '++' or '--' when used in

22N/Apost-increment/decrement mode, or after them when used in

22N/Apre-increment/decrement mode.

22N/A<LI>Do not put a space before ';' when terminating a statement or in a 'for'

22N/Astatement.

22N/A<LI>Do not put a space after '*' when used to dereference a pointer, or on

22N/Aeither side of '->'.

22N/A<LI>Do not put a space after '~'.

22N/A<LI>The '|' operator may either have a space on both sides or it may have no

22N/Aspaces.

37N/A<LI>Do not put a space after a cast.

37N/A</UL>

37N/A

37N/A<H4>Return Values</H4>

37N/AIf a function returns a value, it should be cast to (void) if you don't

37N/Acare what the value is, except for <CODE>printf</CODE><P>

157N/A

215N/AAll error conditions must be handled.<P>

37N/A

37N/AMixing of error status and valid results within a single type should be

22N/Aavoided.<P>

157N/AGood:

157N/A<PRE><CODE>

157N/A os_descriptor_t s;

157N/A os_result_t result;

157N/A

157N/A result = os_socket_create(AF_INET, SOCK_STREAM, 0, &s);

157N/A if (result != OS_R_SUCCESS) {

157N/A /* Do something about the error. */

157N/A return;

157N/A }

157N/A</CODE></PRE>

157N/ANot so good:

157N/A<PRE><CODE>

157N/A int s;

157N/A

157N/A /*

157N/A * Obviously using interfaces like socket() (below) is allowed

157N/A * since otherwise you couldn't call operating system routines; the

157N/A * point is not to write more interfaces like them.

157N/A */

157N/A s = socket(AF_INET, SOCK_STREAM, 0);

289N/A if (s < 0) {

157N/A /* Do something about the error using errno. */

157N/A return;

204N/A }

204N/A</CODE></PRE>

289N/A

204N/A<H4>Integral Types</H4>

157N/ACareful thought should be given to whether an integral type should be

157N/Asigned or unsigned, and to whether a specific size is required. "int"

157N/Ashould be used for generic variables (e.g. iteration counters, array

157N/Asubscripts). Other than for generic variables, if a negative value isn't

157N/Ameaningful, the variable should be unsigned. Assignments and

157N/Acomparisons between signed and unsigned integers should be avoided;

157N/Asuppressing the warnings with casts is not desireable.<P>

289N/A

157N/A<H4>Casting</H4>

157N/ACasting should be avoided when possible. When it is necessary, there

157N/Ashould be no space between the cast and what is being cast.<P>

157N/A

157N/ABad (obviously for more than one reason ...):

157N/A<PRE><CODE>

157N/A (void) malloc(SMBUF);

157N/A</CODE></PRE>

157N/A

157N/A<H4>Clear Success or Failure</H4>

157N/AA function should report success or failure, and do so accurately. It

157N/Ashould never fail silently. Use of Design by Contract can help here.<P>

157N/A

157N/AWhen a function is designed to return results to the caller by

157N/Aassigning to caller variables through pointer arguments, it should

157N/Aperform the assignment only if it succeeds and leave the variables

157N/Aunmodified if it fails.<P>

289N/A

157N/A<H4>Testing Bits</H4>

22N/ABit testing should be as follows:<P>

22N/AGood:

22N/A<PRE><CODE>

22N/A /* Test if flag set. */

22N/A 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 initalized 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>