* (Information about multiprocessing considerations
* here, e.g. locking requirements.)
*
* Reliability:
* (Any reliability concerns should be mentioned here.)
*
* Resources:
* (A rough guide to how resources are used by this module.)
*
* Security:
* (Any security issues are discussed here.)
*
* Standards:
* (Any standards relevant to the module are listed here.)
*/
/***
*** Imports
***/
/* #includes here. */
#include<isc/lang.h>
/***
*** Types
***/
/* (Type definitions here.) */
/***
*** Functions
***/
ISC_LANG_BEGINDECLS
/* (Function declarations here, with full prototypes.) */
ISC_LANG_ENDDECLS
#endif /* ISC_WHATEVER_H */
#### Including Interfaces (.h files)
The first file to be included in a C source file must be config.h. The
config.h file must never be included by any public header file (that is,
any header file that will be installed by `"make install"`).
Try to include only necessary files, not everything under the sun.
Operating-system-specific files should not be included by most modules; if
they are needed, they should be used with `#ifdef` and controlled by
`configure`.
#### Statements
There should be at most one statement per line. The comma operator should
not be used to form compound statements.
Bad:
if (i > 0) {
printf("yes\\n"); i = 0; j = 0;
x = 4, y *= 2;
}
#### Functions
The use of ANSI C function prototypes is required.
The return type of the function should be listed on a line by itself when
specifying the implementation of the function. The opening curly brace
should occur on the same line as the argument list, unless the argument
list is more than one line long:
static inline void
func1(int i) {
/* whatever */
}
int
func2(int first_argument, int next_argument,
int last_argument)
{
/* whatever */
}
To suppress compiler warnings, unused function arguments must be
declared within the function via the `UNUSED()` macro.
In the function body, local variable declarations must be at the beginning
of the function, followed by any `REQUIRE()` statements, then `UNUSED()`
declarations, then all other code, in that order. These sections should be
separated by blank lines.
#### Curly Braces
Curly Braces do not get their own indentation.
An opening brace does not start a new line. The statements enclosed by the
braces should not be on the same line as the opening or closing brace. A
closing brace should be the only thing on the line, unless it's part of an
else clause.
Generally speaking, when a control statement (e.g., `if`, `for` or `while`) has
only a single action associated with it, then no bracing is used around the
statement. Exceptions include when the compiler would complain about an
ambiguous else clause, or when extra bracing improves readability or
safety.
Good:
static void
f(int i) {
if (i > 0) {
printf("yes\\n");
i = 0;
} else
printf("no\\n");
}
Bad:
void f(int i)
{
if(i<0){i=0;printf("wasnegative\\n");}
if (i > 0)
{
printf("yes\\n");
i = 0;
}}
#### Spaces
* DO put a space between operators like `=`, `+`, `==`, etc.
* DO put a space after `,`.
* DO put a space after `;` in a `for` statement.
* DO put spaces after C reserved words such as `if`, `for`, `while`, and `do`.
* DO put a space after `return`, and parenthesize the return value.
* Do NOT put a space between a variable or function name and `(` or `[`.
* Do NOT put a space after the `sizeof` operator name, and DO parenthesize its argument: `malloc(4 * sizeof(long))`.
* Do NOT put a space immediately after a `(` or immediately before a `)`, unless it improves readability. The same goes for `[` and `]`.
* Do NOT put a space before `++` or `--` when used in post-increment/ decrement mode, or after them when used in pre-increment/decrement mode.
* Do NOT put a space before `;` when terminating a statement or in a `for` statement.
* Do NOT put a space after `*` when used to dereference a pointer, or on either side of `->`.
* Do NOT put a space after `~`.
* The `|` operator may either have a space on both sides or it may have no spaces, depending on readability. Either way, if the `|` operator is used more than once in a statement, then the spacing must be consistent.
#### Return Values
If a function returns a value, it should be cast to `(void)` if you don't
care what the value is, except for `printf` and its variants, `fputc`,
File names (`__FILE__`), line numbers (`__LINE__`), function names,
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.
### <a name="pystyle"></a>Python
BIND 9 contains some optional tools written in Python, in the `bin/python` subdirectory. Python scripts are stored in the git repository as `{toolname}.py.in`; and `{toolname}.py` will be generated by `configure` (which determines, among other things, the path to the Python interpreter).
For Python coding, we abide by the Python style guidelines described [here](http://www.python.org/dev/peps/pep-0008/), with a few modifications:
* The `__init__()` method should always be the first one declared in a
class definition, like so:
class Foo:
# constructor definition here
def __init__(self):
...
# other functions may follow
def bar(self):
...
Close all file and socket objects
* All Python standard library objects that have an underlying file
descriptor (fd) should be closed explicitly using the `.close()` method.
* In cases where a file is opened and closed in a single block, it
is often preferable to use the `with` statement:
with open('filename') as f:
do_something_with(f)
### <a name="plstyle"></a>Perl
Perl is NOT required for building, installing, or using the BIND 9 name
server. However, BIND 9 may use Perl for its system test environment, for
certain optional server add-on components, and in some cases for generating
source files (such as `bind9.xsl.h`, converted from `bind9.xsl`) which are
then committed to to the git repository.
Perl 5 is assumed; Perl scripts do not need to work in Perl 4.
Perl source code should follow the conventions for C source code where
applicable.
### <a name="shstyle"></a>Bourne Shell
Shell scripts must be as portable as possible and should therefore conform
strictly to POSIX standards. Shell extensions such as those introduced in
Bash should be avoided. Some pitfalls to avoid:
* To capture the output of a command, use `` `backquotes` `` rather than
`$(parentheses)`
* For arithmetical computation, use `` `expr {expression}` ``, not
`$((expression))`
* To text string length use `` `expr $string : ".*"` `` rather than ``
`expr length $string` ``
* To test for the presence of a string in a file without printing anything
to stdout, use `"grep string filename > /dev/null 2>&1"`, rather than
`"grep -q string filename"`.
* To test for file existence use `"test -f"` rather than `"test -e"`
* Don't use newline (`\\n`) when calling `echo`. Either use another `echo`
statement, or use `"cat << EOF"`.
* To set a variable from outside awk, use `"awk '{...}' var=value"` rather
