Debian Codegraph @

python/doc/source/styleguide_cpp.rst

raw
1 .. _developers_styleguide_cpp:
2
3 C++ coding style guide
4 ======================
5
6 Naming conventions
7 ------------------
8
9 Class names
10 ^^^^^^^^^^^
11 Use camel caps for class names:
12
13 .. code-block:: c++
14
15 class FooBar
16 {
17 ...
18 };
19
20 Function names
21 ^^^^^^^^^^^^^^
22
23 Use lower-case for function names and underscore to separate words:
24
25 .. code-block:: c++
26
27 foo();
28 bar();
29 foo_bar(...);
30
31 Functions returning a value should be given the name of that value,
32 for example:
33
34 .. code-block:: c++
35
36 class Array:
37 {
38 public:
39
40 /// Return size of array (number of entries)
41 std::size_t size() const;
42
43 };
44
45 In the above example, the function should be named ``size`` rather
46 than ``get_size``. On the other hand, a function not returning a value
47 but rather taking a variable (by reference) and assigning a value to
48 it, should use the ``get_foo`` naming scheme, for example:
49
50 .. code-block:: c++
51
52 class Parameters:
53 {
54 public:
55
56 /// Retrieve all parameter keys
57 void get_parameter_keys(std::vector<std::string>& parameter_keys) const;
58
59 };
60
61
62 Variable names
63 ^^^^^^^^^^^^^^
64
65 Use lower-case for variable names and underscore to separate words:
66
67 .. code-block:: c++
68
69 Foo foo;
70 Bar bar;
71 FooBar foo_bar;
72
73 Enum variables and constants
74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
75
76 Enum variables should be lower-case with underscore to separate words:
77
78 .. code-block:: c++
79
80 enum Type {foo, bar, foo_bar};
81
82 We try to avoid using ``#define`` to define constants, but when
83 necessary constants should be capitalized:
84
85 .. code-block:: c++
86
87 #define FOO 3.14159265358979
88
89 File names
90 ^^^^^^^^^^
91
92 Use camel caps for file names if they contain the
93 declaration/definition of a class. Header files should have the suffix
94 ``.h`` and implementation files should have the suffix ``.cpp``:
95
96 .. code-block:: c++
97
98 FooBar.h
99 FooBar.cpp
100
101 Use lower-case for file names that contain utilities/functions (not
102 classes).
103
104 Miscellaneous
105 -------------
106
107 .. _styleguides_cpp_coding_style_indentation:
108
109 Indentation
110 ^^^^^^^^^^^
111
112 Indentation should be two spaces and it should be spaces. Do **not**
113 use tab(s).
114
115 Comments
116 ^^^^^^^^
117
118 Comment your code, and do it often. Capitalize the first letter and
119 don't use punctuation (unless the comment runs over several
120 sentences). Here's a good example from ``TopologyComputation.cpp``:
121
122 .. code-block:: c++
123
124 // Check if connectivity has already been computed
125 if (connectivity.size() > 0)
126 return;
127
128 // Invalidate ordering
129 mesh._ordered = false;
130
131 // Compute entities if they don't exist
132 if (topology.size(d0) == 0)
133 compute_entities(mesh, d0);
134 if (topology.size(d1) == 0)
135 compute_entities(mesh, d1);
136
137 // Check if connectivity still needs to be computed
138 if (connectivity.size() > 0)
139 return;
140
141 ...
142
143 Always use ``//`` for comments and ``///`` for documentation. Never
144 use ``/* foo */``, not even for comments that runs over multiple
145 lines.
146
147 Integers and reals
148 ^^^^^^^^^^^^^^^^^^
149
150 Use ``std::size_t`` instead of ``int`` (unless you really want to use
151 negative integers or memory usage is critical).
152
153 .. code-block:: c++
154
155 std::size_t i = 0;
156 double x = 0.0;
157
158 Placement of brackets and indent style
159 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
160
161 Use the `BSD/Allman <http://en.wikipedia.org/wiki/Indent_style>`_
162 style when formatting blocks of code, i.e., curly brackets following
163 multiline control statements should appear on the next line and should
164 not be indented:
165
166 .. code-block:: c++
167
168 for (std::size_t i = 0; i < 10; i++)
169 {
170 ...
171 }
172
173 For one line statements, omit the brackets:
174
175 .. code-block:: c++
176
177 for (std::size_t i = 0; i < 10; i++)
178 foo(i);
179
180 Header file layout
181 ^^^^^^^^^^^^^^^^^^
182
183 Header files should follow the below template:
184
185 .. code-block:: c++
186
187 // Copyright (C) 2008 Foo Bar
188 //
189 // This file is part of DOLFIN.
190 //
191 // DOLFIN is free software: you can redistribute it and/or modify
192 // it under the terms of the GNU Lesser General Public License as published by
193 // the Free Software Foundation, either version 3 of the License, or
194 // (at your option) any later version.
195 //
196 // DOLFIN is distributed in the hope that it will be useful,
197 // but WITHOUT ANY WARRANTY; without even the implied warranty of
198 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
199 // GNU Lesser General Public License for more details.
200 //
201 // You should have received a copy of the GNU Lesser General Public License
202 // along with DOLFIN. If not, see <http://www.gnu.org/licenses/>.
203 //
204 // Modified by Bar Foo 2008
205
206 #ifndef __FOO_H
207 #define __FOO_H
208
209 namespace dolfin
210 {
211
212 class Bar; // Forward declarations here
213
214 /// Documentation of class
215
216 class Foo
217 {
218 public:
219
220 ...
221
222 private:
223
224 ...
225
226 };
227
228 }
229
230 #endif
231
232 Implementation file layout
233 ^^^^^^^^^^^^^^^^^^^^^^^^^^
234
235 Implementation files should follow the below template:
236
237 .. code-block:: c++
238
239 // Copyright (C) 2008 Foo Bar
240 //
241 // This file is part of DOLFIN.
242 //
243 // DOLFIN is free software: you can redistribute it and/or modify
244 // it under the terms of the GNU Lesser General Public License as published by
245 // the Free Software Foundation, either version 3 of the License, or
246 // (at your option) any later version.
247 //
248 // DOLFIN is distributed in the hope that it will be useful,
249 // but WITHOUT ANY WARRANTY; without even the implied warranty of
250 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
251 // GNU Lesser General Public License for more details.
252 //
253 // You should have received a copy of the GNU Lesser General Public License
254 // along with DOLFIN. If not, see <http://www.gnu.org/licenses/>.
255 //
256 // Modified by Bar Foo 2008
257
258 #include <dolfin/Foo.h>
259
260 using namespace dolfin;
261
262 //-----------------------------------------------------------------------------
263 Foo::Foo() : // variable initialization here
264 {
265 ...
266 }
267 //-----------------------------------------------------------------------------
268 Foo::~Foo()
269 {
270 // Do nothing
271 }
272 //-----------------------------------------------------------------------------
273
274 The horizontal lines above (including the slashes) should be exactly
275 79 characters wide.
276
277 Including header files and using forward declarations
278 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
279
280 Do not use ``#include <dolfin.h>`` or ``#include``
281 ``<dolfin/dolfin_foo.h>`` inside the DOLFIN source tree. Only include
282 the portions of DOLFIN you are actually using.
283
284 Include as few header files as possible and use forward declarations
285 whenever possible (in header files). Put the ``#include`` in the
286 implementation file. This reduces compilation time and minimizes the
287 risk of cyclic dependencies.
288
289 Explicit constructors
290 ^^^^^^^^^^^^^^^^^^^^^
291
292 Make all one argument constructors (except copy constructors)
293 explicit:
294
295 .. code-block:: c++
296
297 class Foo
298 {
299 explicit Foo(std::size_t i);
300 };
301
302 Virtual functions
303 ^^^^^^^^^^^^^^^^^
304
305 Always declare inherited virtual functions as virtual in the
306 subclasses. This makes it easier to spot which functions are virtual.
307
308 .. code-block:: c++
309
310 class Foo
311 {
312 virtual void foo();
313 virtual void bar() = 0;
314 };
315
316 class Bar : public Foo
317 {
318 virtual void foo();
319 virtual void bar();
320 };
321
322 Use of libraries
323 ----------------
324
325 Prefer C++ strings and streams over old C-style ``char*``
326 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328 Use ``std::string`` instead of ``const char*`` and use
329 ``std::istream`` and ``std::ostream`` instead of ``FILE``. Avoid
330 ``printf``, ``sprintf`` and other C functions.
331
332 There are some exceptions to this rule where we need to use old
333 C-style function calls. One such exception is handling of command-line
334 arguments (``char* argv[]``).
335
336 Prefer smart pointers over plain pointers
337 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
338
339 Use ``std::shared_ptr`` and ``std::unique_ptr`` in favour of plain
340 pointers. Smart pointers reduce the likelihood of memory leaks and
341 make ownership clear. Use ``unique_ptr`` for a pointer that is not
342 shared and ``shared_ptr`` when multiple pointers point to the same
343 object.