[[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 (``) 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 `
`. {{{ #!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 The page we are editing may be in XHTML but it is delivered as text/html and thus processed as "tag soup". See the following links for details of why XHTML is problematical: http://friendlybit.com/html/why-xhtml-is-a-bad-idea/ http://hixie.ch/advocacy/xhtml -- sending xhtml as text/html considered harmful As far as market share is concerned - see http://marketshare.hits They quote IE 6 as still having a 25% market share - installed base will be higher as many using Firefox will not have updated it. Even if XHTML worked with other MS browsers, we should not generate content which is unreadable by a quarter of the web population. The only justification for using XHTML is embedded MathML or SVG, etc, but I don't think that applies to our pages. Often one could embed the extra content in an iframe in any case... --MichaelRoberts There is no downside to serving compatible XHTML as text/html. See http://h3h.net/2005/12/xhtml-harmful-to-feelings/ And remember also that Ian Hickson (the guy who started the scaremongering, and tried to kill XHTML with the article linked by Michael Roberts) is now developing HTML 5. Clearly biased - ignore him. The official W3C recommendation is a) use XHTML and b) serve it as text/html to browsers that don't yet fully support application/xhtml+xml -- David Barnard }}} === 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.