Daily bump.
[official-gcc.git] / libcody / CODING.md
blob1ff0a9da76319fde1bff8c4bfca85b9ae2ac72de
1 # Coding standard
3 I guess I should document this, it might not be obvious.
5 libcody is implemented in C++11.  Because it's used in compiler
6 development, we can't use the latest and greatest.
8 The formatting is close to GNU, but with a few differences.
10 ## Extensions to C++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.
17 ## GNU
19 The underlying formatting is GNU style.  Here are a few notes about
20 things that commonly catches programmers unfamiliar with it is:
22 * Spaces between binary operators.  Particularly in a function call,
23   between the name and the open paren:
25   ```c++
26   Fn (a + b, ary[4], *ptr);
27   ```
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!
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:
35   ```c++
36   if (bob)
37     {
38       Frob ();
39       Quux ();
40     }
41   ```
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!
46 * The same is true for a function definition body, except the
47   indentation is zero:
49   ```c++
50   int Foo ()
51     noexcept // indented
52   {
53     return 0;
54   }
55   ```
57 * Initialization bracing is not like scope bracing.  There tends to be
58   more flexibility.
60 * Break lines at 80 chars, this should be /before/ the operator, not after:
62   ```c++
63   a = (b
64        + c);
65   ptr
66   ->MemberFn (stuff);
67   Func
68   (arg);
69   ```
71   Thus you can tell what lines are continued from the previous by
72   looking at their start.  Use parens to control indentation.
74   If you find yourself wanting to break a line at `.`, don't.
75   Refactor your code to avoid needing that.
77 * Template instantiations and C++ casts should have no space before the `<`:
79   ```c++
80   std::vector<int> k;
81   static_cast<T> (arg); // space before the ( though
82   ```
84 * Pointer and reference types need a space before the `*` or `&`, if
85   the preceding token is ascii text (a cpp-identifier):
87   ```
88   int *ptr;
89   int **ptr_ptr;
90   int *&pref = ptr;
91   ```
93   See below a difference in qualifier placement.
95 * Code should compile without warnings.
97 ## Not GNU
99 ### Names
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.
106 ### Type qualifiers
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:
112 ```c++
113 int const foo = 5; // constant int
114 int *const pfoo = nullptr;  // constant pointer to int