libcody/CODING.md

   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 ```