1# Coding standard
2
3I guess I should document this, it might not be obvious.
4
5libcody is implemented in C++11.  Because it's used in compiler
6development, we can't use the latest and greatest.
7
8The formatting is close to GNU, but with a few differences.
9
10## Extensions to C++11
11
12It uses __VA_OPT__ when available, falling back on GNU's variadic
13macro `,#` extension.  This is in the `Assert` macro, so one can have
14multi-argument template instantiations there.  Not that libcody does
15that, but this is code I used elsewhere.
16
17## GNU
18
19The underlying formatting is GNU style.  Here are a few notes about
20things 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
101Unlike GNU code, variants of Camel Case are used.  use `PascalCase`
102for function, type and global variable names.  Use `dromedaryCase` for
103member variables.  Block-scope vars can be `dromedaryCase` or
104`snake_case`, your choice.
105
106### Type qualifiers
107
108Type qualifiers go after the thing they qualify.  You have to do this
109for pointers anyway, and read them inside-out, because, C Just being
110consistent:
111
112```c++
113int const foo = 5; // constant int
114int *const pfoo = nullptr;  // constant pointer to int
115```
116