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

"Some problems"? The page you just linked clearly says "Not supported". IE doesn't even display the page. It asks you to download it. That's not "some issues and problems". Sending XHTML as text/html gives you no benefits over normal HTML and gets you some problems (you can't send just any XHTML, you still have to tweak it to be "HTML-compatible").

Anyway, it was David Anderson who said "no XHTML", not me. I only clarified this page and used more decent arguments for it ("XHTML needs more characters" wasn't exactly a compelling reason). --Nicolas

}}}


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