coding.html revision c8225ba7f2771b23af396a19ee38b2b5d47ae58e
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAn ANSI standard C compiler and library are assumed. Feel free to use any
819fe493f97078521bb6b9a7b97583bef89f5abcMark AndrewsANSI C feature.<P>
ec5347e2c775f027573ce5648b910361aa926c01Automatic UpdaterGiven 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
8077efca7d2ec3b9bf0428386a1ec2fcbcdf437bAutomatic UpdaterUse 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 "_":
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 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.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinMultiline comments should start with "/*" on a line by itself. Subsequent
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlines should have " *" lined-up with the "*" above. The end of the comment
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinshould be " */" on a line by itself, again with the "*" lined-up with the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinone above. Comments should start with a capital letter and end with a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Private variables.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein static int a /* Description of 'a'. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein static int b /* Description of 'b'. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein static char * c /* Description of 'c'. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe following lint and lint-like comments should be used where appropriate:
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews /* ARGSUSED */
1b06367c345e972a0c719a6e821db3e875f20c3bMark Andrews /* FALLTHROUGH */
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews /* NOTREACHED */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein.h files should not rely on other files having been included. .h
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfiles should prevent multiple inclusion. The OS is assumed to prevent
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinmultiple inclusion of its .h files.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein.h files that define modules should have a structure like the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfollowing. Note that <isc/lang.h> should be included by any public
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinheader file to get the ISC_LANG_BEGINDECLS and ISC_LANG_ENDDECLS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinmacros used so the correct name-mangling happens for function
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindeclarations when C++ programs include the file. <isc/lang.h> should
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbe included for private header files or for public files that do not
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindeclare any functions.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Copyright (C) 1998 Internet Software Consortium.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Permission to use, copy, modify, and distribute this software for any
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * purpose with or without fee is hereby granted, provided that the above
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * copyright notice and this permission notice appear in all copies.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#ifndef ISC_WHATEVER_H
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#define ISC_WHATEVER_H 1
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein ***** Module Info
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (Module name here.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (One line description here.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (Extended description and notes here.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (Information about multiprocessing considerations here, e.g. locking
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * requirements.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Reliability:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (Any reliability concerns should be mentioned here.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Resources:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (A rough guide to how resources are used by this module.)
d3cbd6b05c16c6e0e86c1651bda3b3ee06574d62Mark Andrews * (Any security issues are discussed here.)
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews * Standards:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * (Any standards relevant to the module are listed here.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein/* #includes here. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein/* (Type definitions here.) */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *** Functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinISC_LANG_BEGINDECLS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein/* (Function declarations here, with full prototypes.) */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinISC_LANG_ENDDECLS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#endif /* ISC_WHATEVER_H */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe first file to be included in a C source file must be config.h.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe config.h file must never be included by any public header file
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein(that is, any header file that will be installed by "make install").
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinTry to include only necessary files, not everything under the sun.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinOperating-system-specific files should not be included by most modules.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinInclude UNIX "sys" .h files before ordinary C includes.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThere should be at most one statement per line. The comma operator
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinshould not be used to form compound statements.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (i > 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein printf("yes\n"); i = 0; j = 0;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein x = 4, y *= 2;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe use of ANSI C function prototypes is required.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe return type of the function should be listed on a line by itself when
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinspecifying the implementation of the function. The opening curly brace should
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinoccur on the same line as the argument list, unless the argument list is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinmore than one line long.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstatic inline void
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* whatever */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeing(int i, /* other args here */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int last_argument)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return (i * i);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinTo suppress compiler warnings, unused function arguments are declared
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIn the function body, local variable declarations are followed by any
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<CODE>REQUIRE()</CODE>s, <CODE>UNUSED()</CODE> declarations, and other
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincode, in this order. These sections are separated by blank lines.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCurly Braces do not get their own indentation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAn opening brace does not start a new line. The statements enclosed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinby the braces should not be on the same line as the opening or closing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbrace. A closing brace should be the only thing on the line, unless
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinit's part of an else clause.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinGenerally speaking, when a control statement (<CODE>if, for</CODE> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<CODE>while</CODE>) has only a single action associated with it, then no
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbracing is used around the statement. Exceptions include when the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincompiler would complain about an ambiguous else clause, or when extra
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbracing improves the readability (a judgement call biased toward not
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinhaving the braces).<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (i > 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein printf("yes\n");
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein printf("no\n");
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinvoid f(int i)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein printf("yes\n");
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do put a space between operators like '=', '+', '==', etc.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do put a space after ','.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do put a space after ';' in a 'for' statement.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do put a space after 'return', and also parenthesize the return value.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space between a variable or function name and '(' or '['.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space after the "sizeof" operator name, and also
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinparenthesize its argument, as in <CODE>malloc(4 * sizeof(long))</CODE>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space immediately after a '(' or immediately before a ')',
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinunless it improves readability. The same goes for '[' and ']'.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space before '++' or '--' when used in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinpost-increment/decrement mode, or after them when used in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space before ';' when terminating a statement or in a 'for'
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space after '*' when used to dereference a pointer, or on
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeineither side of '->'.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space after '~'.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>The '|' operator may either have a space on both sides or it may have no
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<LI>Do not put a space after a cast.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIf a function returns a value, it should be cast to (void) if you don't
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincare what the value is, except for <CODE>printf</CODE><P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAll error conditions must be handled.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinMixing of error status and valid results within a single type should be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein os_descriptor_t s;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein os_result_t result;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein result = os_socket_create(AF_INET, SOCK_STREAM, 0, &s);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (result != OS_R_SUCCESS) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Do something about the error. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Obviously using interfaces like socket() (below) is allowed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * since otherwise you couldn't call operating system routines; the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * point is not to write more interfaces like them.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein s = socket(AF_INET, SOCK_STREAM, 0);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (s < 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</CODE></PRE>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCareful thought should be given to whether an integral type should be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinsigned or unsigned, and to whether a specific size is required. "int"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinshould be used for generic variables (e.g. iteration counters, array
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinsubscripts). Other than for generic variables, if a negative value isn't
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinmeaningful, the variable should be unsigned. Assignments and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincomparisons between signed and unsigned integers should be avoided;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinsuppressing the warnings with casts is not desireable.<P>
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark AndrewsCasting should be avoided when possible. When it is necessary, there
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrewsshould be no space between the cast and what is being cast.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinBad (obviously for more than one reason ...):
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (void) malloc(SMBUF);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinA function should report success or failure, and do so accurately. It
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinshould never fail silently. Use of Design by Contract can help here.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinBit testing should be as follows:<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Test if flag set. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if ((flags & FOO) != 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Test if flag clear. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if ((flags & BAR) == 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Test if both flags set. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if ((flags & (FOO|BAR)) == (FOO|BAR)) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Test if flag set. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (flags & FOO) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Test if flag clear. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (! (flags & BAR)) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe null pointer value should be referred to with "NULL", not with "0".
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinTesting to see whether a pointer is NULL should be explicit.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char *c = NULL;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (c == NULL) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Do something. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinWhen the data a pointer points to has been freed, or is otherwise no longer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinvalid, the pointer should be set to NULL unless the pointer is part of a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstructure which is itself going to be freed immediately.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* text is initalized here. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein text = NULL;
7ba5dc6485e54258101da72455974dde38d04289Mark AndrewsExplicit testing against zero is required for numeric, non-boolean variables.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (i != 0) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Do something. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* Do something. */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe ?: operator should mostly be avoided. It is tolerated when
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindeciding what value to pass as a parameter to a function, such as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfrequently happens with printf, and also when a simple (non-compound)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinvalue is being used in assignment or as part of a calculation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIn particular, using the ternary operator to specify a return value is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein printf("%c is%s a number.\n", c, isdigit(c) ? "" " NOT");
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if (gp.length + (go < 16384 ? 2 : 3) >= name->length) {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return (success ? ISC_R_SUCESS : ISC_R_FAILURE);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinVariables should not have their values assigned or changed when being
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinpassed as parameters, except perhaps for the increment and decrement
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinoperators.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein malloc(size = 20);
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews fputc(c++, stdout);
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark AndrewsAll public interfaces to functions, macros, typedefs, and
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrewsvariables provided by the library, should use names of the form
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews{library}_{module}_{what}, such as:
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews isc_buffer_t /* typedef */
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews dns_name_setbuffer(name, buffer) /* function */
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews ISC_LIST_HEAD(list) /* macro */
3d711f2f75cb9a9ddcbf1fca9b2de192e75340e6Mark Andrews isc_commandline_argument /* variable */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinhowever, structures which are typedef'd generally have the name of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintypedef sans the final _t:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein struct dns_rbtnode {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein /* ... members ... */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinGenerally speaking macros are defined with all capital letters, but
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinthis is not universally consistent (eg, numerous isc_buffer_{foo}
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe {module} and {what} segments of the name do not have underscores
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinseparating natural word elements, as demonstrated in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinisc_commandline_argument and dns_name_setbuffer above. The {module}
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinpart is usually the same as the basename of the source file, but
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinsometimes other {module} interfaces appear within one file, such as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindns_label_* interfaces in lib/dns/name.c. However, in the public
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlibraries the file name must be the same as some module interface
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinprovided by the file; e.g., dns_rbt_* interfaces would not be declared
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinin a file named redblack.c (in lieu of any other dns_redblack_*
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeininterfaces in the file).<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe one notable exception to this naming rule is the interfaces
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinprovided by <isc/util.h>. There's a large caveat associated with the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinpublic description of this file that it is hazardous to use because it
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinpollutes the general namespace.<P>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinWhen a module provides an interface for internal use by other modules
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinin the library, it should use the same naming convention
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindescribed for the public interfaces, except {library} and {module}
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinare separated by a double-underscore. This indicates that the name is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeininternal, its API is not as formal as the public API, and thus it
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinmight change without any sort of notice.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinWhen an object is allocated from the heap, all fields in the object must be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeininitialized.<P>