Changes between Version 1 and Version 2 of CodingStyle


Ignore:
Timestamp:
Apr 25, 2007, 12:34:34 PM (17 years ago)
Author:
Nicolas
Comment:

Required manual changes to automatic conversion.

Legend:

Unmodified
Added
Removed
Modified

  • CodingStyle

    v1 v2  
    11= BOINC coding style =
    2 
    32
    43==  All languages ==
    … …  
    1110 * C++ .h files often contain both interface and implementation.         Clearly divide these.
    1211
    13 
    1412===  Code documentation ===
    1513
    16  * .C files have a comment at the top saying what's         in the file (and perhaps what isn't).
     14 * .C files have a comment at the top saying what's in the file (and perhaps what isn't).
    1715 * Functions are preceded by a comment saying what they do.
    1816 * Structs and classes are preceded by a comment saying what they are.
    1917
    20 
    2118===  Naming ===
    2219
    23  * Names should be descriptive without being verbose         (local variables names may be short)
     20 * Names should be descriptive without being verbose (local variables names may be short)
    2421 * Class and type names, and #defined symbols, are all upper case,         with underscores to separate words.
    25  * Variable and function names are all lower case,         with underscores to separate words.
     22 * Variable and function names are all lower case, with underscores to separate words.
    2623 * No mixed case names
    2724
    28 
    29 ===  Indentation ===
     25=== Indentation ===
    3026
    3127 * Each level of indentation is 4 spaces (not a tab).
    3228 * multi-line function call:
    3329{{{
    34         func(
    35             blah, blah, blah, blah, blah,
    36             blah, blah, blah, blah, blah
    37         );
    38         }}}
     30func(
     31    blah, blah, blah, blah, blah,
     32    blah, blah, blah, blah, blah
     33);
     34}}}
    3935 * switch statements: case labels are at same indent level as switch
    4036{{{
    41         switch (foo) {
    42         case 1:
    43             ...
    44             break;
    45         case 2:
    46             ...
    47             break;
    48         }
    49         }}}
     37switch (foo) {
     38case 1:
     39    ...
     40    break;
     41case 2:
     42    ...
     43    break;
     44}
     45}}}
    5046
     47=== Constants ===
    5148
    52 ===  Constants ===
     49There should be few numeric constants in code. Generally they should be `#define`s.
    5350
    54 
    55 
    56 ===  Braces ===
     51=== Braces ===
    5752
    5853 * Opening curly brace goes at end of line (not next line):
    5954{{{
    60         if (foobar) {
    61             ...
    62         } else if (blah) {
    63             ...
    64         } else {
    65             ...
    66         }
    67     }}}
     55if (foobar) {
     56    ...
     57} else if (blah) {
     58    ...
     59} else {
     60    ...
     61}
     62}}}
    6863 * always use curly braces on multi-line if statements
    6964{{{
    70         if (foo)
    71             return blah;        // WRONG
    72     }}}
     65if (foo)
     66    return blah;     // WRONG
     67}}}
    7368 * 1-line if() statments are OK:
    7469{{{
    75         if (foo) return blah;
    76     }}}
     70if (foo) return blah;
     71}}}
    7772
    7873
    79 ===  comments and #ifdefs ===
     74=== Comments and #ifdefs ===
    8075
    81  * use // for all comments
     76 * use `//` for all comments
    8277 * comment out blocks of code as follows:
    8378{{{
    84         #if 0
    85             ...
    86         #endif
    87     }}}
     79#if 0
     80    ...
     81#endif
     82}}}
    8883
     84== C++ specific ==
    8985
    90 ==  C++ specific ==
     86=== Includes ===
    9187
    92 ===  Includes ===
    93 
    94  * 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)
     88 * 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)
    9589 * Includes should go from general (<stdio.h>) to specific (thisfile.h)
    9690
     91=== Extern declarations ===
    9792
    98 ===  extern declarations ===
     93foo.h should have 'extern' declarations for all public functions and variables in foo.C There should be no 'extern' statements in .C files.
    9994
     95=== Use of static ===
    10096
     97 * if a function or variable is used in only one file, declare it static.
    10198
    102 ===  Use of static ===
    103 
    104  * if a function or variable is used only in 1 file, declare it static.
    105 
    106 
    107 ===  Things to avoid unless there's a truly compelling reason: ===
     99=== Things to avoid unless there's a truly compelling reason: ===
    108100
    109101 * inline functions
    … …  
    111103 * templates
    112104
    113 
    114 ===  Things to avoid ===
     105=== Things to avoid ===
    115106
    116107 * use typedef (not #define) to define types
    117  * don't use memset() or memcpy() to initialize or copy classes         that are non-C compatible.         Write a default constructor and a copy constructor.
     108 * don't use memset() or memcpy() to initialize or copy classes         that are non-C compatible. Write a default constructor and a copy constructor.
    118109
     110=== Error codes ===
    119111
    120 ===  error codes ===
     112 * (almost) all functions should return an integer error code.         Nonzero means error. See lib/errornumbers.h for a list of error codes.
     113 * Calls to functions that return an error code should check the code. Generally they should return on error, e.g.:
     114{{{
     115retval = blah();
     116if (retval) return retval;
     117}}}
    121118
    122  * (almost) all functions should return an integer error code.         Nonzero means error.         See lib/errornumbers.h for a list of error codes.
    123  * Calls to functions that return an error code should         check the code.         Generally they should return on error, e.g.:
    124 {{{
    125             retval = blah();
    126             if (retval) return retval;
    127     }}}
    128 
    129 
    130 ===  structure definitions ===
    131 
    132 
     119=== Structure definitions ===
    133120
    134121{{{
     122struct FOO {
     123    ...
     124};
     125}}}
     126You can then declare variables as:
     127{{{
     128FOO x;
     129}}}
    135130
    136     struct FOO {
    137         ...
    138     };
    139     }}}
    140       You can then declare variables as:
    141 {{{
    142     FOO x;
    143     }}}
    144 
    145 ==  PHP specific ==
     131== PHP specific ==
    146132
    147133=== Getting POST and GET data ===
    148  Remember that hackers can pass arbitrary values in POST and GET, and they can use this to do SQL injections and other exploits.
    149  * Do not access $_POST or $_GET directly.
    150  * Use get_int(), get_str(), post_int() and post_str()     (from util.inc) to get POST and GET data.
    151  * If a POST or GET value will be used in a SQL query,     use process_user_text() to escape it.
     134Remember that hackers can pass arbitrary values in POST and GET, and they can use this to do SQL injections and other exploits.
     135 * Do not access `$_POST` or `$_GET` directly.
     136 * Use `get_int()`, `get_str()`, `post_int()` and `post_str()` (from `util.inc`) to get POST and GET data.
     137 * If a POST or GET value will be used in a SQL query, use `process_user_text()` to escape it.
    152138