Home | History | Annotate | Line # | Download | only in libcody 
      1 # Coding standard
      2 
      3 I guess I should document this, it might not be obvious.
      4 
      5 libcody is implemented in C++11.  Because it's used in compiler
      6 development, we can't use the latest and greatest.
      7 
      8 The formatting is close to GNU, but with a few differences.
      9 
     10 ## Extensions to C++11
     11 
     12 It uses __VA_OPT__ when available, falling back on GNU's variadic
     13 macro `,#` extension.  This is in the `Assert` macro, so one can have
     14 multi-argument template instantiations there.  Not that libcody does
     15 that, but this is code I used elsewhere.
     16 
     17 ## GNU
     18 
     19 The underlying formatting is GNU style.  Here are a few notes about
     20 things that commonly catches programmers unfamiliar with it is:
     21 
     22 * Spaces between binary operators.  Particularly in a function call,
     23   between the name and the open paren:
     24 
     25   ```c++
     26   Fn (a + b, ary[4], *ptr);
     27   ```
     28 
     29   In general GNU style uses a lot more whitespace than Clang-style.
     30   We're not trying to cram as much code as possible onto a page!
     31 
     32 * Scope braces are always on a line of their own, indented by 2
     33   spaces, if they're a sub-statement of an `if`, `for` or whatever:
     34 
     35   ```c++
     36   if (bob)
     37     {
     38       Frob ();
     39       Quux ();
     40     }
     41   ```
     42 
     43   Conditions and loops containing a single statement should not use `{}`.
     44   FWIW this was my personal indentation scheme, before I even met GNU code!
     45 
     46 * The same is true for a function definition body, except the
     47   indentation is zero:
     48 
     49   ```c++
     50   int Foo ()
     51     noexcept // indented
     52   {
     53     return 0;
     54   }
     55   ```
     56 
     57 * Initialization bracing is not like scope bracing.  There tends to be
     58   more flexibility.
     59 
     60 * Break lines at 80 chars, this should be /before/ the operator, not after:
     61 
     62   ```c++
     63   a = (b
     64        + c);
     65   ptr
     66   ->MemberFn (stuff);
     67   Func
     68   (arg);
     69   ```
     70 
     71   Thus you can tell what lines are continued from the previous by
     72   looking at their start.  Use parens to control indentation.
     73 
     74   If you find yourself wanting to break a line at `.`, don't.
     75   Refactor your code to avoid needing that.
     76 
     77 * Template instantiations and C++ casts should have no space before the `<`:
     78 
     79   ```c++
     80   std::vector<int> k;
     81   static_cast<T> (arg); // space before the ( though
     82   ```
     83 
     84 * Pointer and reference types need a space before the `*` or `&`, if
     85   the preceding token is ascii text (a cpp-identifier):
     86 
     87   ```
     88   int *ptr;
     89   int **ptr_ptr;
     90   int *&pref = ptr;
     91   ```
     92 
     93   See below a difference in qualifier placement.
     94 
     95 * Code should compile without warnings.
     96 
     97 ## Not GNU
     98 
     99 ### Names
    100 
    101 Unlike GNU code, variants of Camel Case are used.  use `PascalCase`
    102 for function, type and global variable names.  Use `dromedaryCase` for
    103 member variables.  Block-scope vars can be `dromedaryCase` or
    104 `snake_case`, your choice.
    105 
    106 ### Type qualifiers
    107 
    108 Type qualifiers go after the thing they qualify.  You have to do this
    109 for pointers anyway, and read them inside-out, because, C Just being
    110 consistent:
    111 
    112 ```c++
    113 int const foo = 5; // constant int
    114 int *const pfoo = nullptr;  // constant pointer to int
    115 ```
    116