[[PageOutline]]

= BOINC coding style =

== All languages == #all-lang

=== Code factoring === #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' (unrelated stuff), split it up.
 * C++ `.h` files often contain both interface and implementation. Clearly divide these.

=== Error codes === #error-codes

Most functions should return an integer error code.
Nonzero means error. See [source:boinc/lib/error_numbers.h lib/error_numbers.h] for a list of error codes.
Exceptions:
 * PHP database access functions, which use the mysql_* convention
   that zero means error, and you call mysql_error() or mysql_error_string() to find details.
 * Functions that return whether a condition holds; such functions should have
   descriptive names like `is_job_finished()`.
 * Functions that return a number or other type, and for which no errors are possible.

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;
}}}

=== Code documentation === #docs

 * All 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 === #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 === #indent

 * 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 === #constants

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

=== Braces (C++ and PHP) === #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 === #comments

 * For C++ and PHP, use `//` for all comments.
 * End multi-line comments with an empty comment line, e.g.
{{{
// This function does blah blah
// Call it when blah blah
//
function foo() {
}
}}}

== C++ specific == #cpp

=== Includes === #includes

 * A `.cpp` file should have the minimum set of #includes to get that particular file to compile
  (e.g. the includes needed by `foo.cpp` should be in `foo.cpp`, not `foo.h`).
 * For readability, includes should be ordered from general (`<stdio.h>`) to specific (`foo.h`).
  However, this order shouldn't matter.

=== Extern declarations === #extern

 * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp`
   .There should be no `extern` statements in `.cpp` files.

=== Use of static === #static

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

=== Things to avoid unless there's a compelling reason: === #try-avoid

 * Operator or function overloading.
 * Templates.

=== Things to avoid === #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.
 * Dynamic memory allocation.  Functions shouldn't return pointers to malloc'd items.



=== Structure definitions === #structs

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

=== Comments ===
Comment out blocks of code as follows:
{{{
#if 0
    ...
#endif
}}}
== PHP specific == #php

=== HTML === #html

PHP scripts should output "HTML 4.01 Transitional".
The HTML should pass the [http://validator.w3.org/ W3C validator].
This means, e.g., you must have quotes around attributes
that have non-alpha characters in them.
However, all-alpha attributes need not have quotes,
and tags like <br> and <p> need not be closed.

The HTML need not be XHTML.

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

=== Getting POST and GET data === #post-and-get

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