]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | Ceph Coding style |
2 | ----------------- | |
3 | ||
4 | Coding style is most important for new code and (to a lesser extent) | |
5 | revised code. It is not worth the churn to simply reformat old code. | |
6 | ||
7 | C code | |
8 | ------ | |
9 | ||
10 | For C code, we conform by the Linux kernel coding standards: | |
11 | ||
9f95a23c | 12 | https://www.kernel.org/doc/Documentation/process/coding-style.rst |
7c673cae FG |
13 | |
14 | ||
15 | C++ code | |
16 | -------- | |
17 | ||
18 | For C++ code, things are a bit more complex. As a baseline, we use Google's | |
19 | coding guide: | |
20 | ||
21 | https://google.github.io/styleguide/cppguide.html | |
22 | ||
23 | ||
24 | As an addendum to the above, we add the following guidelines, organized | |
25 | by section. | |
26 | ||
27 | * Naming > Type Names: | |
28 | ||
29 | Google uses CamelCaps for all type names. We use two naming schemes: | |
30 | ||
11fdf7f2 TL |
31 | - for naked structs (simple data containers), lower case with _t. |
32 | Yes, _t also means typedef. It's perhaps not ideal. | |
7c673cae | 33 | |
11fdf7f2 TL |
34 | struct my_type_t { |
35 | int a = 0, b = 0; | |
36 | void encode(...) ... | |
37 | ... | |
7c673cae FG |
38 | }; |
39 | ||
40 | - for full-blown classes, CamelCaps, private: section, accessors, | |
41 | probably not copyable, etc. | |
42 | ||
43 | * Naming > Variable Names: | |
44 | ||
45 | Google uses _ suffix for class members. That's ugly. We'll use | |
11fdf7f2 | 46 | a m_ prefix, like so, or none at all. |
7c673cae FG |
47 | |
48 | class Foo { | |
49 | public: | |
50 | int get_foo() const { return m_foo; } | |
51 | void set_foo(int foo) { m_foo = foo; } | |
52 | ||
53 | private: | |
54 | int m_foo; | |
55 | }; | |
11fdf7f2 | 56 | |
7c673cae FG |
57 | * Naming > Constant Names: |
58 | ||
59 | Google uses kSomeThing for constants. We prefer SOME_THING. | |
60 | ||
61 | * Naming > Function Names: | |
62 | ||
63 | Google uses CamelCaps. We use_function_names_with_underscores(). | |
64 | ||
65 | Accessors are the same, {get,set}_field(). | |
66 | ||
67 | * Naming > Enumerator Names: | |
68 | ||
69 | Name them like constants, as above (SOME_THING). | |
70 | ||
71 | * Comments > File Comments: | |
72 | ||
73 | Don't sweat it, unless the license varies from that of the project | |
9f95a23c | 74 | (LGPL2.1 or LGPL3.0) or the code origin isn't reflected by the git history. |
7c673cae FG |
75 | |
76 | * Formatting > Tabs: | |
77 | Indent width is two spaces. When runs of 8 spaces can be compressed | |
78 | to a single tab character, do so. The standard Emacs/Vim settings | |
79 | header is: | |
80 | ||
81 | // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*- | |
9f95a23c | 82 | // vim: ts=8 sw=2 smarttab ft=cpp |
7c673cae FG |
83 | |
84 | * Formatting > Conditionals: | |
85 | ||
86 | - No spaces inside conditionals please, e.g. | |
87 | ||
88 | if (foo) { // okay | |
89 | ||
90 | if ( foo ) { // no | |
91 | ||
11fdf7f2 | 92 | - Always use newline following if, and use braces: |
7c673cae FG |
93 | |
94 | if (foo) { | |
11fdf7f2 | 95 | bar; // like this, even for a one-liner |
7c673cae FG |
96 | } |
97 | ||
11fdf7f2 TL |
98 | if (foo) |
99 | bar; // no, usually harder to parse visually | |
100 | ||
101 | if (foo) bar; // no | |
102 | ||
103 | if (foo) { bar; } // definitely no | |
7c673cae | 104 | |
11fdf7f2 | 105 | * Header Files -> The `#define` Guard: |
7c673cae | 106 | |
11fdf7f2 | 107 | `#pragma once` is allowed for simplicity at the expense of |
9f95a23c | 108 | portability since `#pragma once` is widely supported and is known |
11fdf7f2 | 109 | to work on GCC and Clang. |
7c673cae FG |
110 | |
111 | ||
112 | The following guidelines have not been followed in the legacy code, | |
113 | but are worth mentioning and should be followed strictly for new code: | |
114 | ||
115 | * Header Files > Function Parameter Ordering: | |
116 | ||
117 | Inputs, then outputs. | |
118 | ||
119 | * Classes > Explicit Constructors: | |
120 | ||
121 | You should normally mark constructors explicit to avoid getting silent | |
122 | type conversions. | |
123 | ||
124 | * Classes > Copy Constructors: | |
125 | ||
126 | - Use defaults for basic struct-style data objects. | |
127 | ||
128 | - Most other classes should DISALLOW_COPY_AND_ASSIGN. | |
129 | ||
130 | - In rare cases we can define a proper copy constructor and operator=. | |
131 | ||
132 | * Other C++ Features > Reference Arguments: | |
133 | ||
134 | Only use const references. Use pointers for output arguments. | |
135 | ||
136 | * Other C++ Features > Avoid Default Arguments: | |
137 | ||
138 | They obscure the interface. | |
11fdf7f2 TL |
139 | |
140 | ||
141 | Python code | |
142 | ----------- | |
143 | ||
144 | For new python code, PEP-8 should be observed: | |
145 | ||
146 | https://www.python.org/dev/peps/pep-0008/ | |
147 | ||
148 | Existing code can be refactored to adhere to PEP-8, and cleanups are welcome. | |
149 | ||
150 | ||
151 | JavaScript / TypeScript | |
152 | ----------------------- | |
153 | ||
154 | For Angular code, we follow the official Angular style guide: | |
155 | ||
156 | https://angular.io/guide/styleguide | |
157 | ||
158 | To check whether your code is conformant with the style guide, we use a | |
159 | combination of TSLint, Codelyzer and Prettier: | |
160 | ||
161 | https://palantir.github.io/tslint/ | |
162 | http://codelyzer.com/ | |
163 | https://prettier.io/ | |
164 |