[[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 ===

PHP scripts should output HTML 4.01, not XHTML. XHTML isn't supported by many browsers. Serving XHTML with a text/html MIME type is not a solution either (it's not XHTML anymore, it becomes invalid HTML).

This means no self-closing tags like `<br />`.

{{{
#!comment
"XHTML isn't supported by many browsers." - please point at least one; IE 7, IE 8, FF 2+, FF 3+, Opera 9+ support XHTML Safari 3+; those browsers are used by +98% of peoples so where is problem? HTML 4.01 is obsolete - it was designed in 1999... --Simek

Wikipedia says: "The notable exception is Internet Explorer by Microsoft; rather than rendering application/xhtml+xml content, a dialog box invites the user to save the content to disk instead. Both Internet Explorer 7 (released in 2006) and the initial beta version of Internet Explorer 8 (released in March 2008) exhibit this behavior, and it is unclear whether this will be resolved in a future release." --Nicolas

Results of test for XHTML compatibility: http://www.w3.org/People/mimasa/test/xhtml/media-types/results
It's true that IE has some issues and problems with XHTML+XML but most of today's websites uses XHTML 1.0+ and in my opinion BOINC should also migrate to this standard.
For example: Wikipedia and Microsoft uses XHTML 1.0 Transitional (MS uses web standard not compatibility with their Web Browsers? Huh?) and even BOINC Trac uses XHTML 1.0 Strict. --Simek

}}}


=== 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.