wiki:CodingStyle

Version 31 (modified by davea, 6 years ago) (diff)

--

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.

Error codes

  • (Almost) all functions should return an integer error code. Nonzero means error. See lib/error_numbers.h for a list of error codes. The only exception to this is 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.
  • 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

  • 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

  • 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 #defines.

Braces (C++ and PHP)

  • 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

  • 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

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

  • 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

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

Things to avoid unless there's a compelling reason:

  • 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.
  • Dynamic memory allocation. Functions shouldn't return pointers to malloc'd items.

Structure definitions

struct FOO {
    ...
};

You can then declare variables as:

FOO x;

Comments

Comment out blocks of code as follows:

#if 0
    ...
#endif

PHP specific

HTML

PHP scripts should output "HTML 4.01 Transitional". The HTML should pass the 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

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 database abstraction layer.
  • If a POST or GET value will be used in a database query, use BoincDb::escape_string to escape it.