[[PageOutline]]

= BOINC coding style =

== All languages ==

=== Code factoring ===

 * If code is repeated, factor it out and make it into a function.
 * If a function becomes longer than 100 lines or so, split it up.
 * If a file is becoming 'landfill', split it up.
 * C++ `.h` files often contain both interface and implementation. Clearly divide these.

=== Code documentation ===

 * `.C` files have a comment at the top saying what's in the file (and perhaps what isn't).
 * Functions are preceded by a comment saying what they do.
 * structs and classes are preceded by a comment saying what they are.

=== Naming ===

 * Names should be descriptive without being verbose (local variables names may be short).
 * Class and type names, and #defined symbols, are all upper case, with underscores to separate words.
 * Variable and function names are all lower case, with underscores to separate words.
 * No mixed case names.

=== Indentation ===

 * Each level of indentation is 4 spaces (not a tab).
 * Multi-line function call:
{{{
func(
    blah, blah, blah, blah, blah,
    blah, blah, blah, blah, blah
);
}}}
 * {{{switch}}} statements: {{{case}}} labels are at same indent level as {{{switch}}}:
{{{
switch (foo) {
case 1:
    ...
    break;
case 2:
    ...
    break;
}
}}}

=== Constants ===

 * There should be few numeric constants in code. Generally they should be `#define`s.

=== Braces ===

 * Opening curly brace goes at end of line (not next line):
{{{
if (foobar) {
    ...
} else if (blah) {
    ...
} else {
    ...
}
}}}
 * Always use curly braces on multi-line `if` statements.
{{{
if (foo)
    return blah;     // WRONG
}}}
 * 1-line `if()` statements are OK:
{{{
if (foo) return blah;
}}}


=== Comments and #ifdefs ===

 * Use `//` for all comments.
 * Comment out blocks of code as follows:
{{{
#if 0
    ...
#endif
}}}

== C++ specific ==

=== Includes ===

 * A `.C` file should have the minimum set of #includes to get that particular file to compile (e.g. the includes needed by {{{foo.C}}} should be in {{{foo.C}}}, not {{{foo.h}}}).
 * Includes should be ordered from general (`<stdio.h>`) to specific (`thisfile.h`).

=== Extern declarations ===

 * {{{foo.h}}} should have '{{{extern}}}' declarations for all public functions and variables in {{{foo.C}}} There should be no '{{{extern}}}' statements in {{{.C}}} files.

=== Use of static ===

 * If a function or variable is used in only one file, declare it {{{static}}}.

=== Things to avoid unless there's a truly compelling reason: ===

 * Inline functions.
 * Operator or function overloading.
 * Templates.

=== Things to avoid ===

 * Use `typedef` (not `#define`) to define types.
 * Don't use `memset()` or `memcpy()` to initialize or copy classes that are non-C compatible. Write a default constructor and a copy constructor instead.

=== Error codes ===

 * (Almost) all functions should return an integer error code. Nonzero means error. See [source:trunk/boinc/lib/error_numbers.h lib/error_numbers.h] for a list of error codes.
 * Calls to functions that return an error code should check the code. Generally they should return non-zero on error, e.g.:
{{{
retval = blah();
if (retval) return retval;
}}}

=== Structure definitions ===

{{{
struct FOO {
    ...
};
}}}
You can then declare variables as:
{{{
FOO x;
}}}

== PHP specific ==

=== HTML ===

It's OK to output HTML rather than XHTML.
I have yet to hear a convincing reason for the latter,
and it's more characters.

=== Getting POST and GET data ===

Do not access `$_POST` or `$_GET` directly.
Use `get_int()`, `get_str()`, `post_int()` and `post_str()` (from `util.inc`) to get POST and GET data.
These undo the effects of PHP magic quotes.

=== Database access ===
 * Use the [PhpDb database abstraction layer].
 * If a POST or GET value will be used in a database query, use `BoincDb::escape_string` to escape it.