Changes between Initial Version and Version 1 of Programming Style Guide


Ignore:
Timestamp:
10/22/10 16:04:31 (10 years ago)
Author:
beki01
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Programming Style Guide

    v1 v1  
     1= Programming Style Guide for PET, version 1.0 = 
     2 
     3== Discussion: == 
     4 
     5 * Although starting symbol names with underscore conflicts with some 
     6   recommendations for the C standard, i want to stick with it because 
     7   i've seen no clash up to now 
     8 
     9== Indentation == 
     10 * Proper indentation and paragraphing are mandatory 
     11 * Always use spaces for indentation, '''no tabs! ''' 
     12 * Use two spaces per indentation level 
     13 * Delete trailing white space 
     14 * Only a single statement per line 
     15 * A line of code should not be longer than 80 characters 
     16 * If you have to break a line 
     17   * break after a comma 
     18   * break before an operator 
     19 * If a method does not fit on one screen then it is probably too long 
     20 * Use spaces appropriately 
     21   * Yes: `grandTotal = invoice.total() + getAmountDue();` 
     22   * No:   `grandTotal=invoice.total()+getAmountDue();` 
     23 * No spaces around period or arrow (field/pointer access) 
     24 * Minimise the use of vertical white space 
     25 * Only use ASCII characters, or UTF-8 encoding, if necessary 
     26 * put opening braces after function or method headers, `if` , `for` , etc. 
     27   onto the same line 
     28 * putting `else` onto a new line is recommended for long `if`--`else` 
     29   statements 
     30 
     31== Naming Conventions == 
     32 * `CamelCase`  for Classes (without leading {{{`t'}}}) 
     33 * Method and local Variable names should adhere to the C standard: small with 
     34   underscores to separate multi-word names. 
     35 * `CONSTANTS`  all upper case, underscores to separate multi-word names 
     36 * Avoid too long names to save horizontal space, if you can keep clarity 
     37 * Do not abbreviate names by removing vowels where not necessary 
     38   * `append_signature(String signature)` 
     39   * `appnd_sgntr(String sgntr)` 
     40 * Capitalize only the first letter in acronyms 
     41   * `loadXmlDocument()` 
     42   * `loadXMLDocument()` 
     43 * Avoid names that are similar or differ only in case: `sqlDataBase` vs. 
     44   `sqlDatabase` 
     45 * Use `is_`  or `has_`  as prefix for methods/functions returning `bool` 
     46 * The shorter the name of a variable, the smaller its scope! 
     47 * data fields should start with an underscore, especially private ones 
     48 
     49== Documentation == 
     50 * Write comments that can be processed with doxygen 
     51 * Pay attention to punctuation, spelling, and grammar to make reading easy 
     52 * Keep comments in sync with the code 
     53 
     54== Programming Conventions == 
     55 * Use C `FILE` pointers, `fprintf`, `char *` only where absolutely necessary 
     56   because of efficiency reasons 
     57 * Use redundant parentheses wherever it clarifies the order of operations 
     58   inside an expression. 
     59 * Put blocks in brackets, even if they only contain a single statement  
     60   `if (a.equals(b)) c = b; ` 
     61 * Place constants on the left side of comparisons 
     62   * Yes: `   if ( 0 == x ) ...` 
     63   * No:   `   if ( x == 0 ) ...` 
     64 * Try to avoid `return` in the middle of a method 
     65 * Use `break` or `continue` only when it makes the code more readable 
     66 * Declare local variables immediately before their use, and in the narrowest 
     67   scope possible 
     68 * Use prefix instead of postfix ++ and -- where possible, '''especially''' 
     69   when used with iterators! 
     70   [http://stackoverflow.com/questions/24901/is-there-a-performance-difference-between-i-and-i-in-c] 
     71 * Provide a copy constructor and assignment operator only when necessary 
     72   [http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Copy_Constructors#Copy_Constructors] 
     73 
     74=== Constructors === 
     75 * Don’t put much work into constructors, write an init() method if necessary 
     76 * Either implement an assignment operator and a copy constructor for a class 
     77   or explicitly inhibit copying 
     78 * Use the C++ keyword `explicit` for constructors with one argument 
     79 
     80=== Declaration Order === 
     81 * Your class definition should start with its `public:` section, followed by 
     82   its `protected:` section and then its `private:` section. If any of these 
     83   sections are empty, omit them. 
     84 * Within each section, the declarations generally should be in the following 
     85   order: 
     86   * Typedefs and Enums 
     87   * Constants (static const data members) 
     88   * Constructors 
     89   * Destructor 
     90   * Methods, including static methods 
     91   * Data Members (except static const data members) 
     92 * Friend declarations should always be in the private section, and the 
     93   `DISALLOW_COPY_AND_ASSIGN` macro invocation should be at the end of the 
     94   `private:`  section. It should be the last thing in the class. 
     95 * Method definitions in the corresponding `.cpp` file should be the same as 
     96   the declaration order, as much as possible. 
     97 * Do not put large method definitions inline in the class definition. Usually, 
     98   only trivial or performance-critical, and very short, methods may be 
     99   defined inline. 
     100 
     101=== Class and Method Visibility === 
     102 * Be as restrictive as possible! 
     103 * Use `friend` with care, e.g., to avoid making something public that is 
     104   needed only by a tightly coupled class 
     105 * Use `const`  as much as possible. 
     106 
     107=== File organisation === 
     108 * All header files should have `#define`  guards 
     109 * Make include files as independent of each other as possible, don’t use an 
     110   include if forward declaration would suffice 
     111 * Every header file must compile on its own 
     112 * Sort and group `#include` s in a meaningful way 
     113 * In general, put declarations in header files, definitions in source files