coding.html revision 7e985260692958285fc3c128fdb27867a865db26
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsAn ANSI standard C compiler and library are assumed. Feel free to use any
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsANSI C feature.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsGiven a reasonable set of things to warn about (e.g. -W -Wall for gcc), the
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsgoal is to compile with no warnings.
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsAll source files should have a copyright. The copyright year(s)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsshould be kept current. The files and the copyright year(s) should be
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsUse tabs. Spaces are only allowed when needed to line up a continued
26440aaebba1acb5c8810f7faa26ad3b7553762eMark Andrewsexpression. In the following example, spaces used for indentation are
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsindicated with "_":
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews printf("this is going to be %s very long %s statement\n",
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews _______"a", "printf");
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsVertical whitespace is also encouraged for improved code legibility by
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsgrouping closely related statements and then separating them with a
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewssingle empty line. There should not, however, be more than one empty
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsadjacent line anywhere.
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsLines should not be longer than 79 characters, even if it requires
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsviolating the indentation rules to do so. Since ANSI is assumed, the
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsbest way to deal with strings that extend past column 79 is to break
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsthem into two or more sections separated from each other by a newline
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsand indentation:
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews puts("This string got very far to the "
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews "left and wrapped. ANSI catenation "
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews "rules will turn this into one
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews "long string.");
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsComments should be used anytime they improve the readability of the code.<P>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsComments may be single-line or multiline. A single-line comment should be
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsat the end of the line of there is other text on the line, and should start
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsin the same column as other nearby end-of-line comments. The comment
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsshould be at the same indentation level as the text it is referring to.
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsMultiline comments should start with "/*" on a line by itself. Subsequent
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewslines should have " *" lined-up with the "*" above. The end of the comment
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsshould be " */" on a line by itself, again with the "*" lined-up with the
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsone above. Comments should start with a capital letter and end with a
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Private variables.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews static int a /* Description of 'a'. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews static int b /* Description of 'b'. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews static char * c /* Description of 'c'. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThe following lint and lint-like comments should be used where appropriate:
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* ARGSUSED */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* FALLTHROUGH */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* NOTREACHED */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* VARARGS */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews.h files should not rely on other files having been included. .h
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsfiles should prevent multiple inclusion. The OS is assumed to prevent
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsmultiple inclusion of its .h files.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews.h files that define modules should have a structure like the
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsfollowing. Note that <isc/lang.h> should be included by any public
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsheader file to get the ISC_LANG_BEGINDECLS and ISC_LANG_ENDDECLS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsmacros used so the correct name-mangling happens for function
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsdeclarations when C++ programs include the file. <isc/lang.h> should
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsbe included for private header files or for public files that do not
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsdeclare any functions.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Copyright (C) 1998 Internet Software Consortium.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Permission to use, copy, modify, and distribute this software for any
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * purpose with or without fee is hereby granted, provided that the above
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * copyright notice and this permission notice appear in all copies.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews#ifndef ISC_WHATEVER_H
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews#define ISC_WHATEVER_H 1
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews ***** Module Info
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Module name here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (One line description here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Extended description and notes here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Information about multiprocessing considerations here, e.g. locking
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * requirements.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Reliability:
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Any reliability concerns should be mentioned here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Resources:
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (A rough guide to how resources are used by this module.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Any security issues are discussed here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Standards:
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * (Any standards relevant to the module are listed here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews/* #includes here. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews/* (Type definitions here.) */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews *** Functions
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsISC_LANG_BEGINDECLS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews/* (Function declarations here, with full prototypes.) */
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsISC_LANG_ENDDECLS
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews#endif /* ISC_WHATEVER_H */
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThe first file to be included in a C source file must be config.h.
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThe config.h file must never be included by any public header file
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews(that is, any header file that will be installed by "make install").
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsTry to include only necessary files, not everything under the sun.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsOperating-system-specific files should not be included by most modules.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsInclude UNIX "sys" .h files before ordinary C includes.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThere should be at most one statement per line. The comma operator
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsshould not be used to form compound statements.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews if (i > 0) {
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews printf("yes\n"); i = 0; j = 0;
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews x = 4, y *= 2;
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThe use of ANSI C function prototypes is required.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsThe return type of the function should be listed on a line by itself when
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsspecifying the implementation of the function. The opening curly brace should
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsoccur on the same line as the argument list, unless the argument list is
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsmore than one line long.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsstatic inline void
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* whatever */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsg(int i, /* other args here */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews int last_argument)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews return (i * i);
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsTo suppress compiler warnings, unused function arguments are declared
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsIn the function body, any <CODE>REQUIRE()</CODE>s are placed
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsimmediately after the local variabled, followed by any
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsCurly Braces do not get their own indentation.
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsAn opening brace does not start a new line. The statements enclosed
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsby the braces should not be on the same line as the opening or closing
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsbrace. A closing brace should be the only thing on the line, unless
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsit's part of an else clause.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsGenerally speaking, when a control statement (<CODE>if, for</CODE> or
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<CODE>while</CODE>) has only a single action associated with it, then no
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsbracing is used around the statement. Exceptions include when the
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewscompiler would complain about an ambiguous else clause, or when extra
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsbracing improves the readability (a judgement call biased toward not
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewshaving the braces).<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews if (i > 0) {
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews printf("yes\n");
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews printf("no\n");
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsvoid f(int i)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews printf("yes\n");
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do put a space between operators like '=', '+', '==', etc.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do put a space after ','.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do put a space after ';' in a 'for' statement.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do put a space after 'return', and also parenthesize the return value.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space between a variable or function name and '(' or '['.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space after the "sizeof" operator name, and also
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsparenthesize its argument, as in <CODE>malloc(4 * sizeof(long))</CODE>.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space immediately after a '(' or immediately before a ')',
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsunless it improves readability. The same goes for '[' and ']'.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space before '++' or '--' when used in
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewspost-increment/decrement mode, or after them when used in
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space before ';' when terminating a statement or in a 'for'
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space after '*' when used to dereference a pointer, or on
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewseither side of '->'.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space after '~'.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>The '|' operator may either have a space on both sides or it may have no
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<LI>Do not put a space after a cast.
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsIf a function returns a value, it should be cast to (void) if you don't
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewscare what the value is, except for <CODE>printf</CODE><P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsAll error conditions must be handled.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsMixing of error status and valid results within a single type should be
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews os_descriptor_t s;
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews os_result_t result;
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews result = os_socket_create(AF_INET, SOCK_STREAM, 0, &s);
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews if (result != OS_R_SUCCESS) {
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* Do something about the error. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Obviously using interfaces like socket() (below) is allowed
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * since otherwise you couldn't call operating system routines; the
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * point is not to write more interfaces like them.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews s = socket(AF_INET, SOCK_STREAM, 0);
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews if (s < 0) {
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews /* Do something about the error using errno. */
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews</CODE></PRE>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsCareful thought should be given to whether an integral type should be
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewssigned or unsigned, and to whether a specific size is required. "int"
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsshould be used for generic variables (e.g. iteration counters, array
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewssubscripts). Other than for generic variables, if a negative value isn't
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewsmeaningful, the variable should be unsigned. Assignments and
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrewscomparisons between signed and unsigned integers should be avoided;
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewssuppressing the warnings with casts is not desireable.<P>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark AndrewsCasting should be avoided when possible. When it is necessary, there
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsshould be no space between the cast and what is being cast.<P>
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsBad (obviously for more than one reason ...):
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_*