Changes between Version 32 and Version 33 of CodingStyle


Ignore:
Timestamp:
08/29/19 18:48:33 (2 months ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodingStyle

    v32 v33  
    11[[PageOutline]]
    22
    3 = BOINC coding style =
     3= Software and information architecture =
     4
     5Since I first wrote it in 2002, BOINC has evolved continuously and fairly smoothly.
     6It's now an extremely powerful system,
     7but its code size is fairly small,
     8and the code is malleable (easy to change and extend).
     9I don't see any barriers to BOINC's continued evolution.
     10
     11This success is due in large part to BOINC's architecture.
     12I'll try to articulate some of the principles behind this architecture.
     13
     14== Simplicity and brevity ==
     15
     16The most important principle is: make the code as simple as possible.
     17
     18To a large extent, shorter is simpler. So:
     19
     20 * Given two possible implementation, use the shorter one.
     21 * If you're writing something new, and it needs a function
     22   that might be of general utility,
     23   check whether it already exists (in lib/ or html/inc)
     24   rather than writing it yourself.
     25 * If code is repeated, factor it out and make it into a function.
     26   Don't copy and paste code.
     27
     28Related principles:
     29
     30 * If you're adding a new mechanism,
     31   try to make it more general than the immediate need,
     32   without making it more complicated.
     33 * If a function becomes longer than 100 lines or so, split it up.
     34 * If a file is becoming too big,
     35   or has a bunch of unrelated stuff, split it up.
     36
     37== Uniformity ==
     38
     39Imitate the style and structure of the code that's already there,
     40even if you don't like it.
     41
     42== Data architecture ==
     43
     44BOINC stores information in various forms.
     45Guidelines:
     46
     47 * '''MySQL database''':
     48  The DB server is a potential performance bottleneck,
     49  and there is a code overhead for DB tables
     50  (you need to write interface functions in C++ and/or PHP,
     51  and you need to write web pages or scripts for editing data).
     52  So use the DB only when it's necessary
     53  (e.g. because you need indices for large data) and avoid creating new tables.
     54  Don't use referential constraints; instead, check for lookups returning null.
     55 * '''XML fields in DB tables''':
     56  Simplify DB design by storing information in XML in DB fields
     57  (for example, computing preferences and job file lists).
     58  This can eliminate the need for separate tables.
     59 * '''XML files''':
     60  BOINC uses XML format both for internal state (e.g. client_state.xml)
     61  and configuration files (cc_config.xml on the client, project.xml on the server).
     62  Sometimes we use enclosing tags for multiple items
     63  (e.g. <tasks> in project.xml); sometimes we don't.
     64  Either is fine - imitate what's already there.
     65 * '''PHP and/or C++ code''':
     66  If data is used only in PHP, put it in a PHP data structure.
     67  You can assume that project admins are able to edit these
     68  (e.g. html/project/project.inc).
     69
     70== Avoid over-engineering ==
     71
     72If you make a big change to solve a problem that never actually arises,
     73that's over-engineering.
     74Avoid it.
     75
     76There are various things (HTTP headers, message boards, XML parsing)
     77where we've had to choose between using someone else's library or doing it ourselves.
     78There are always tradeoffs.
     79If we have something that works and is stable (e.g. XML parsing), leave it.
     80
     81In general, big changes should be undertaken only if it's certain
     82that there's going to be a big reward.
     83Big changes introduce bugs, and end up costing more than you think.
     84One exception: occasionally I'll make a change whose only effect
     85is to shorten or simplify the code.
     86
     87= Coding style =
    488
    589== All languages == #all-lang
    6 
    7 === Code factoring === #factoring
    8 
    9  * If code is repeated, factor it out and make it into a function.
    10  * If a function becomes longer than 100 lines or so, split it up.
    11  * If a file is becoming 'landfill' (unrelated stuff), split it up.
    12  * C++ `.h` files often contain both interface and implementation. Clearly divide these.
    1390
    1491=== Error codes === #error-codes
     
    34111 * All files have a comment at the top saying what's in the file (and perhaps what isn't).
    35112 * Functions are preceded by a comment saying what they do.
    36  * structs and classes are preceded by a comment saying what they are.
     113 * structs and classes are preceded by a comment saying what they represent.
    37114
    38115=== Naming === #naming
     
    105182== C++ specific == #cpp
    106183
     184 * C++ `.h` files often contain both interface and implementation. Clearly divide these.
     185
    107186=== Includes === #includes
    108187
     
    114193=== Extern declarations === #extern
    115194
    116  * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp`
    117    .There should be no `extern` statements in `.cpp` files.
     195 * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp`.
     196   There should be no `extern` statements in `.cpp` files.
    118197
    119198=== Use of static === #static
     
    123202=== Things to avoid unless there's a compelling reason: === #try-avoid
    124203
    125  * Operator or function overloading.
     204 * Operator and function overloading.
    126205 * Templates.
     206 * Stream I/O; use printf() and scanf().
    127207
    128208=== Things to avoid === #avoid
     
    132212   Write a default constructor and a copy constructor instead.
    133213 * Dynamic memory allocation.  Functions shouldn't return pointers to malloc'd items.
    134 
    135 
    136214
    137215=== Structure definitions === #structs
     
    178256 * Use the [PhpDb database abstraction layer].
    179257 * If a POST or GET value will be used in a database query, use `BoincDb::escape_string` to escape it.
     258