summaryrefslogtreecommitdiffstats
path: root/CodingStyle
blob: b5e42fcf81d080b56375f740ba283536998d1304 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
Ceph Coding style
-----------------

Coding style is most important for new code and (to a lesser extent)
revised code.  It is not worth the churn to simply reformat old code.

C code
------

For C code, we conform by the Linux kernel coding standards:

    https://www.kernel.org/doc/Documentation/CodingStyle


C++ code
--------

For C++ code, things are a bit more complex.  As a baseline, we use Google's
coding guide:

    https://google.github.io/styleguide/cppguide.html


As an addendum to the above, we add the following guidelines, organized
by section.

* Naming > Type Names:

    Google uses CamelCaps for all type names.  We use two naming schemes:

    - for naked structs (simple data containers), lower case with _t.
      Yes, _t also means typedef.  It's perhaps not ideal.

        struct my_type_t {
          int a = 0, b = 0;
	  void encode(...) ...
	  ...
        };

    - for full-blown classes, CamelCaps, private: section, accessors,
      probably not copyable, etc.

* Naming > Variable Names:

   Google uses _ suffix for class members.  That's ugly.  We'll use
   a m_ prefix, like so, or none at all.

        class Foo {
	 public:
          int get_foo() const { return m_foo; }
          void set_foo(int foo) { m_foo = foo; }

         private:
          int m_foo;
   	};

* Naming > Constant Names:

   Google uses kSomeThing for constants.  We prefer SOME_THING.

* Naming > Function Names:

   Google uses CamelCaps.  We use_function_names_with_underscores().

   Accessors are the same, {get,set}_field().

* Naming > Enumerator Names:

   Name them like constants, as above (SOME_THING).

* Comments > File Comments:

   Don't sweat it, unless the license varies from that of the project
   (LGPL2.1) or the code origin isn't reflected by the git history.

* Formatting > Tabs:
  Indent width is two spaces.  When runs of 8 spaces can be compressed
  to a single tab character, do so. The standard Emacs/Vim settings
  header is:

// -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
// vim: ts=8 sw=2 smarttab

* Formatting > Conditionals:

   - No spaces inside conditionals please, e.g.

        if (foo) {   // okay

        if ( foo ) { // no

   - Always use newline following if, and use braces:

        if (foo) {
          bar;         // like this, even for a one-liner
        }

	if (foo)
	  bar;         // no, usually harder to parse visually

        if (foo) bar;  // no

	if (foo) { bar; }  // definitely no

* Header Files -> The `#define` Guard:

  `#pragma once` is allowed for simplicity at the expense of
   portability sinces `#pragma once` is wildly supported and is known
   to work on GCC and Clang.


The following guidelines have not been followed in the legacy code,
but are worth mentioning and should be followed strictly for new code:

* Header Files > Function Parameter Ordering:

    Inputs, then outputs.

* Classes > Explicit Constructors:

    You should normally mark constructors explicit to avoid getting silent
type conversions.

* Classes > Copy Constructors:

    - Use defaults for basic struct-style data objects.

    - Most other classes should DISALLOW_COPY_AND_ASSIGN.

    - In rare cases we can define a proper copy constructor and operator=.

* Other C++ Features > Reference Arguments:

    Only use const references.  Use pointers for output arguments.

* Other C++ Features > Avoid Default Arguments:

    They obscure the interface.


Python code
-----------

For new python code, PEP-8 should be observed:

    https://www.python.org/dev/peps/pep-0008/

Existing code can be refactored to adhere to PEP-8, and cleanups are welcome.


JavaScript / TypeScript
-----------------------

For Angular code, we follow the official Angular style guide:

    https://angular.io/guide/styleguide

To check whether your code is conformant with the style guide, we use a
combination of TSLint, Codelyzer and Prettier:

    https://palantir.github.io/tslint/
    http://codelyzer.com/
    https://prettier.io/