blob: 7071e1d0e085966144a065c4d5bbfb31f86188c7 [file] [log] [blame]
Alexander Afanasyev766cea72014-04-24 19:16:42 -07001ndn-cxx Code Style and Coding Guidelines
2========================================
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07003
4Based on
5
6 * "C++ Programming Style Guidelines" by Geotechnical Software Services, Copyright © 1996 – 2011.
7 The original document is available at `<http://geosoft.no/development/cppstyle.html>`_
8
9 * NDN Platform "C++, C, C#, Java and JavaScript Code Guidelines".
10 The original document available at `<http://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/>`_
11
Junxiao Shi28af1dc2014-11-06 15:53:32 -0700121. Code layout
13--------------
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070014
151.1. The code layout should generally follow the GNU coding standard layout for C,
16extended it to C++.
17
18 * Do not use tabs for indentation.
19 * Indentation spacing is 2 spaces.
20 * Lines should be within a reasonable range. Lines longer than 100 columns should
21 generally be avoided.
22
231.2. Whitespace
24
25 * Conventional operators (``if``, ``for``, ``while``, and others) should be
26 surrounded by a space character.
27 * Commas should be followed by a white space.
28 * Semicolons in for statments should be followed by a space character.
29
30 Examples:
31
32 .. code-block:: c++
33
34 a = (b + c) * d; // NOT: a=(b+c)*d
35
36 while (true) { // NOT: while(true)
37 ...
38
39 doSomething(a, b, c, d); // NOT: doSomething(a,b,c,d);
40
41 for (i = 0; i < 10; i++) { // NOT: for(i=0;i<10;i++){
42 ...
43
441.3. Namespaces should have the following form:
45
46 .. code-block:: c++
47
48 namespace example {
49
50 code;
51 moreCode;
52
53 } // namespace example
54
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050055 Note that code inside namespace is **not** indented. Avoid the following:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070056
57 .. code-block:: c++
58
59 // NOT
60 //
61 // namespace example {
62 //
63 // code;
64 // moreCode;
65 //
66 // } // namespace example
67
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500681.4. Class declarations should have the following form:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070069
70 .. code-block:: c++
71
72 class SomeClass : public BaseClass
73 {
74 public:
75 ... <public methods> ...
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050076
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070077 protected:
78 ... <protected methods> ...
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050079
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070080 private:
81 ... <private methods> ...
82
83 public:
84 ... <public data> ...
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050085
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070086 protected:
87 ... <protected data> ...
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050088
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070089 private:
90 ... <private data> ...
91 };
92
93 ``public``, ``protected``, ``private`` may be repeated several times without
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -050094 interleaving (e.g., public, public, public, private, private) if this improves
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070095 readability of the code.
96
97 Nested classes can be defined in appropriate visibility section, either in methods
98 block, data block, or in a separate section (depending which one provides better code
99 readability).
100
1011.5. Method and function definitions should have the following form:
102
103 .. code-block:: c++
104
105 void
106 someMethod()
107 {
108 ...
109 }
110
111 void
112 SomeClass::someMethod()
113 {
114 ...
115 }
116
1171.6. The ``if-else`` class of statements should have the following form:
118
119 .. code-block:: c++
120
121 if (condition) {
122 statements;
123 }
124
125 if (condition) {
126 statements;
127 }
128 else {
129 statements;
130 }
131
132 if (condition) {
133 statements;
134 }
135 else if (condition) {
136 statements;
137 }
138 else {
139 statements;
140 }
141
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07001421.7. A ``for`` statement should have the following form:
143
144 .. code-block:: c++
145
146 for (initialization; condition; update) {
147 statements;
148 }
149
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500150 An empty ``for`` statement should have the following form:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700151
152 .. code-block:: c++
153
154 for (initialization; condition; update)
155 ;
156
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500157 This emphasizes the fact that the ``for`` statement is empty and makes it obvious for
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700158 the reader that this is intentional. Empty loops should be avoided however.
159
1601.8. A ``while`` statement should have the following form:
161
162 .. code-block:: c++
163
164 while (condition) {
165 statements;
166 }
167
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07001681.9. A ``do-while`` statement should have the following form:
169
170 .. code-block:: c++
171
172 do {
173 statements;
174 } while (condition);
175
1761.10. A ``switch`` statement should have the following form:
177
178 .. code-block:: c++
179
180 switch (condition) {
Wentao Shang3aa4f412015-08-18 21:12:50 -0700181 case ABC: // 2 space indent
182 statements; // 4 space indent
Davide Pesavento1c597a12017-10-06 15:34:24 -0400183 NDN_CXX_FALLTHROUGH;
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700184
Wentao Shang3aa4f412015-08-18 21:12:50 -0700185 case DEF:
186 statements;
187 break;
188
189 case XYZ: {
190 statements;
191 break;
192 }
193
194 default:
195 statements;
196 break;
197 }
198
199 When curly braces are used inside a ``case`` block, the braces must cover the entire
200 ``case`` block.
201
202 .. code-block:: c++
203
204 switch (condition) {
205 // Correct style
206 case A0: {
207 statements;
208 break;
209 }
210
211 // Correct style
212 case A1: {
213 statements;
Davide Pesavento1c597a12017-10-06 15:34:24 -0400214 NDN_CXX_FALLTHROUGH;
Wentao Shang3aa4f412015-08-18 21:12:50 -0700215 }
216
217 // Incorrect style: braces should cover the entire case block
218 case B: {
219 statements;
220 }
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700221 statements;
222 break;
223
Wentao Shang3aa4f412015-08-18 21:12:50 -0700224 default:
225 break;
226 }
227
228 The following style is still allowed when none of the ``case`` blocks has curly braces.
229
230 .. code-block:: c++
231
232 switch (condition) {
233 case ABC: // no indent
234 statements; // 2 space indent
Davide Pesavento1c597a12017-10-06 15:34:24 -0400235 NDN_CXX_FALLTHROUGH;
Wentao Shang3aa4f412015-08-18 21:12:50 -0700236
237 case DEF:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700238 statements;
239 break;
240
241 default:
242 statements;
243 break;
244 }
245
Davide Pesavento1c597a12017-10-06 15:34:24 -0400246 The ``NDN_CXX_FALLTHROUGH;`` annotation must be included whenever there is
247 a case without a break statement. Leaving the break out is a common error,
248 and it must be made clear that it is intentional when it is not there.
249 Moreover, modern compilers will warn when a case that falls through is not
250 explicitly annotated.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700251
2521.11. A ``try-catch`` statement should have the following form:
253
254 .. code-block:: c++
255
256 try {
257 statements;
258 }
Davide Pesaventocd183d22015-09-23 16:40:28 +0200259 catch (const Exception& exception) {
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700260 statements;
261 }
262
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07002631.12. The incompleteness of split lines must be made obvious.
264
265 .. code-block:: c++
266
267 totalSum = a + b + c +
268 d + e;
269 function(param1, param2,
270 param3);
271 for (int tableNo = 0; tableNo < nTables;
272 tableNo += tableStep) {
273 ...
274 }
275
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500276 Split lines occur when a statement exceeds the column limit given in rule 1.1. It is
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700277 difficult to give rigid rules for how lines should be split, but the examples above should
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500278 give a general hint. In general:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700279
280 * Break after a comma.
281 * Break after an operator.
282 * Align the new line with the beginning of the expression on the previous line.
283
284 Exceptions:
285
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500286 * The following is standard practice with ``operator<<``:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700287
288 .. code-block:: c++
289
290 std::cout << "Something here "
291 << "Something there" << std::endl;
292
2931.13. When class variables need to be initialized in the constructor, the initialization
294should take the following form:
295
296 .. code-block:: c++
297
298 SomeClass::SomeClass(int value, const std::string& string)
299 : m_value(value)
300 , m_string(string)
301 ...
302 {
303 }
304
305 Each initialization should be put on a separate line, starting either with the colon
306 for the first initialization or with comma for all subsequent initializations.
307
Junxiao Shi45c13842014-11-02 15:36:04 -07003081.14. A range-based ``for`` statement should have the following form:
309
310 .. code-block:: c++
311
312 for (T i : range) {
313 statements;
314 }
315
Junxiao Shicf698182014-11-03 08:37:42 -07003161.15. A lambda expression should have the following form:
317
318 .. code-block:: c++
319
320 [&capture1, capture2] (T1 arg1, T2 arg2) {
321 statements;
322 }
323
324 [&capture1, capture2] (T1 arg1, T2 arg2) mutable {
325 statements;
326 }
327
328 [this] (T arg) {
329 statements;
330 }
331
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500332 If the lambda has no parameters, ``()`` should be omitted.
Junxiao Shicf698182014-11-03 08:37:42 -0700333
334 .. code-block:: c++
335
336 [&capture1, capture2] {
337 statements;
338 }
339
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500340 Either capture-default (``[&]`` or ``[=]``) is permitted, but its usage should be minimized.
341 Only use a capture-default when it significantly simplifies code and improves readability.
Junxiao Shicf698182014-11-03 08:37:42 -0700342
343 .. code-block:: c++
344
345 [&] (T arg) {
346 statements;
347 }
348
349 [=] (T arg) {
350 statements;
351 }
352
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500353 Trailing return type should be omitted whenever possible. Add it only when the compiler
354 cannot deduce the return type automatically, or when it improves readability.
355 ``()`` is required by the C++ standard when ``mutable`` or a trailing return type is used.
Junxiao Shicf698182014-11-03 08:37:42 -0700356
357 .. code-block:: c++
358
359 [] (T arg) -> int {
360 statements;
361 }
362
363 [] () -> int {
364 statements;
365 }
366
367 If the function body has only one line, and the whole lambda expression can fit in one line,
368 the following form is also acceptable:
369
370 .. code-block:: c++
371
372 [&capture1, capture2] (T1 arg1, T2 arg2) { statement; }
373
374 No-op can be written in a more compact form:
375
376 .. code-block:: c++
377
378 []{}
379
Junxiao Shi8b12a5a2014-11-25 10:42:47 -07003801.16. List initialization should have the following form:
381
382 .. code-block:: c++
383
384 T object{arg1, arg2};
385
386 T{arg1, arg2};
387
388 new T{arg1, arg2};
389
390 return {arg1, arg2};
391
392 function({arg1, arg2}, otherArgument);
393
394 object[{arg1, arg2}];
395
396 T({arg1, arg2})
397
398 class Class
399 {
400 private:
Davide Pesaventoe6e6fde2016-04-16 14:44:45 +0200401 T m_member = {arg1, arg2};
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700402 static T s_member = {arg1, arg2};
403 };
404
405 Class::Class()
406 : m_member{arg1, arg2}
407 {
408 }
409
410 T object = {arg1, arg2};
411
412 An empty braced-init-list is written as ``{}``. For example:
413
414 .. code-block:: c++
415
416 T object{};
417
418 T object = {};
419
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07004202. Naming Conventions
421---------------------
422
4232.1. C++ header files should have the extension ``.hpp``. Source files should have the
424extension ``.cpp``
425
426 File names should be all lower case. If the class name
427 is a composite of several words, each word in a file name should be separated with a
428 dash (-). A class should be declared in a header file and defined in a source file
429 where the name of the files match the name of the class.
430
431 ::
432
433 my-class.hpp, my-class.cpp
434
435
4362.2. Names representing types must be written in English in mixed case starting with upper case.
437
438 .. code-block:: c++
439
440 class MyClass;
441 class Line;
442 class SavingsAccount;
443
4442.3. Variable names must be written in English in mixed case starting with lower case.
445
446 .. code-block:: c++
447
448 MyClass myClass;
449 Line line;
450 SavingsAccount savingsAccount;
451 int theAnswerToLifeTheUniverseAndEverything;
452
4532.4. Named constants (including enumeration values) must be all uppercase using underscore
454to separate words.
455
456 .. code-block:: c++
457
458 const int MAX_ITERATIONS = 25;
459 const std::string COLOR_RED = "red";
460 static const double PI = 3.14;
461
462 In some cases, it is a better (or is the only way for complex constants in header-only
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500463 classes) to implement the value as a method.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700464
465 .. code-block:: c++
466
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500467 static int // declare constexpr if possible
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700468 getMaxIterations()
469 {
470 return 25;
471 }
472
4732.5. Names representing methods or functions must be commands starting with a verb and
474written in mixed case starting with lower case.
475
476 .. code-block:: c++
477
478 std::string
479 getName()
480 {
481 ...
482 }
483
484 double
485 computeTotalWidth()
486 {
487 ...
488 }
489
4902.6. Names representing namespaces should be all lowercase.
491
492 .. code-block:: c++
493
494 namespace model {
495 namespace analyzer {
496
497 ...
498
499 } // namespace analyzer
500 } // namespace model
501
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05005022.7. Names representing generic template types should be a single uppercase letter.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700503
504 .. code-block:: c++
505
506 template<class T> ...
507 template<class C, class D> ...
508
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500509 However, when a template parameter represents a certain concept and is expected
510 to have a certain interface, the name should be explicitly spelled out.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700511
512 .. code-block:: c++
513
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500514 template<class InputIterator> ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700515 template<class Packet> ...
516
5172.8. Abbreviations and acronyms must not be uppercase when used as name.
518
519 .. code-block:: c++
520
521 exportHtmlSource(); // NOT: exportHTMLSource();
522 openDvdPlayer(); // NOT: openDVDPlayer();
523
5242.9. Global variables should have ``g_`` prefix
525
526 .. code-block:: c++
527
528 g_mainWindow.open();
529 g_applicationContext.getName();
530
531 In general, the use of global variables should be avoided. Consider using singleton
532 objects instead.
533
5342.10. Private class variables should have ``m_`` prefix. Static class variables should have
535``s_`` prefix.
536
537 .. code-block:: c++
538
539 class SomeClass
540 {
541 private:
542 int m_length;
543
544 static std::string s_name;
545 };
546
547
5482.11. Variables with a large scope should have long (explicit) names, variables with a small
549scope can have short names.
550
551 Scratch variables used for temporary storage or indices are best kept short. A
552 programmer reading such variables should be able to assume that its value is not used
553 outside of a few lines of code. Common scratch variables for integers are ``i``,
554 ``j``, ``k``, ``m``, ``n`` and for characters ``c`` and ``d``.
555
5562.12. The name of the object is implicit, and should be avoided in a method name.
557
558 .. code-block:: c++
559
560 line.getLength(); // NOT: line.getLineLength();
561
562 The latter seems natural in the class declaration, but proves superfluous in use, as
563 shown in the example.
564
5652.13. The terms ``get/set`` must be used where an attribute is accessed directly.
566
567 .. code-block:: c++
568
569 employee.getName();
570 employee.setName(name);
571
572 matrix.getElement(2, 4);
573 matrix.setElement(2, 4, value);
574
5752.14. The term ``compute`` can be used in methods where something is computed.
576
577 .. code-block:: c++
578
579 valueSet.computeAverage();
580 matrix.computeInverse()
581
582 Give the reader the immediate clue that this is a potentially time-consuming operation,
583 and if used repeatedly, he might consider caching the result. Consistent use of the term
584 enhances readability.
585
5862.15. The term ``find`` can be used in methods where something is looked up.
587
588 .. code-block:: c++
589
590 vertex.findNearestVertex();
591 matrix.findMinElement();
592
593 Give the reader the immediate clue that this is a simple look up method with a minimum
594 of computations involved. Consistent use of the term enhances readability.
595
5962.16. Plural form should be used on names representing a collection of objects.
597
598 .. code-block:: c++
599
600 vector<Point> points;
601 int values[];
602
603 Enhances readability since the name gives the user an immediate clue of the type of
604 the variable and the operations that can be performed on its elements.
605
6062.17. The prefix ``n`` should be used for variables representing a number of objects.
607
608 .. code-block:: c++
609
610 nPoints, nLines
611
612 The notation is taken from mathematics where it is an established convention for
613 indicating a number of objects.
614
615
Eric Newberry436e46f2018-06-10 21:45:57 -07006162.18. The suffix ``Num`` or ``No`` should be used for variables representing an entity number.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700617
618 .. code-block:: c++
619
Eric Newberry436e46f2018-06-10 21:45:57 -0700620 tableNum, tableNo, employeeNum, employeeNo
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700621
6222.19. The prefix ``is``, ``has``, ``need``, or similar should be used for boolean variables and
623methods.
624
625 .. code-block:: c++
626
627 isSet, isVisible, isFinished, isFound, isOpen
628 needToConvert, needToFinish
629
6302.20. Complement names must be used for complement operations, reducing complexity by
631symmetry.
632
633 ::
634
635 get/set, add/remove, create/destroy, start/stop, insert/delete,
636 increment/decrement, old/new, begin/end, first/last, up/down, min/max,
637 next/previous (and commonly used next/prev), open/close, show/hide,
638 suspend/resume, etc.
639
640 Pair ``insert/erase`` should be preferred. ``insert/delete`` can also be used if it
641 does not conflict with C++ delete keyword.
642
6432.21. Variable names should not include reference to variable type (do not use Hungarian
644notation).
645
646 .. code-block:: c++
647
648 Line* line; // NOT: Line* pLine;
649 // NOT: Line* linePtr;
650
651 size_t nPoints; // NOT lnPoints
652
653 char* name; // NOT szName
654
6552.22. Negated boolean variable names should be avoided.
656
657 .. code-block:: c++
658
659 bool isError; // NOT: isNoError
660 bool isFound; // NOT: isNotFound
661
6622.23. Enumeration constants recommended to prefix with a common type name.
663
664 .. code-block:: c++
665
666 enum Color {
667 COLOR_RED,
668 COLOR_GREEN,
669 COLOR_BLUE
670 };
671
6722.24. Exceptions can be suffixed with either ``Exception`` (e.g., ``SecurityException``) or
673``Error`` (e.g., ``SecurityError``).
674
675 The recommended method is to declare exception class ``Exception`` or ``Error`` as an
676 inner class, from which the exception is thrown. For example, when declaring class
677 ``Foo`` that can throw errors, one can write the following:
678
679 .. code-block:: c++
680
681 #include <stdexcept>
682
683 class Foo
684 {
Junxiao Shi68b53852018-07-25 13:56:38 -0600685 public:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700686 class Error : public std::runtime_error
687 {
688 public:
Junxiao Shi68b53852018-07-25 13:56:38 -0600689 // You can inherit constructors from std::runtime_error like this:
690 using std::runtime_error::runtime_error;
691
692 // Additional constructors, if desired, can be declared like this:
693 Error(const std::string& what, const std::exception& inner)
694 : std::runtime_error(what + ": " + inner.what())
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700695 {
696 }
697 };
698 };
699
700 In addition to that, if class Foo is a base class or interface for some class
701 hierarchy, then child classes should should define their own ``Error`` or
702 ``Exception`` classes that are inherited from the parent's Error class.
703
704
7052.25. Functions (methods returning something) should be named after what they return and
706procedures (void methods) after what they do.
707
708 Increase readability. Makes it clear what the unit should do and especially all the
709 things it is not supposed to do. This again makes it easier to keep the code clean of
710 side effects.
711
7123. Miscellaneous
713----------------
714
7153.1. Exceptions can be used in the code, but should be used only in exceptional cases and
716not in the primary processing path.
717
7183.2. Header files must contain an include guard.
719
720 For example, header file located in ``module/class-name.hpp`` or in
721 ``src/module/class-name.hpp`` should have header guard in the following form:
722
723 .. code-block:: c++
724
725 #ifndef APP_MODULE_CLASS_NAME_HPP
726 #define APP_MODULE_CLASS_NAME_HPP
727 ...
728 #endif // APP_MODULE_CLASS_NAME_HPP
729
730 The name should follow the location of the file inside the source tree and prevents
731 naming conflicts. Header guard should be prefixed with the application/library name
732 to avoid conflicts with other packaged and libraries.
733
7343.3. Header files which are in the same source distribution should be included in
735``"quotes"``, if possible with a path relative to the source file. Header files for
736system and other external libraries should be included in ``<angle brackets>``.
737
738 .. code-block:: c++
739
740 #include <string>
741 #include <boost/lexical_cast.hpp>
742
743 #include "util/random.hpp"
744
Junxiao Shi4f92d872017-07-25 22:04:48 +00007453.4. Include statements should be grouped. Same-project headers should be included first.
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500746Leave an empty line between groups of include statements. Sort alphabetically within a group.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700747
748 .. code-block:: c++
749
Junxiao Shi4f92d872017-07-25 22:04:48 +0000750 #include "detail/pending-interest.hpp"
751 #include "util/random.hpp"
752
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700753 #include <fstream>
754 #include <iomanip>
755
756 #include <boost/lexical_cast.hpp>
757 #include <boost/regex.hpp>
758
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700759
7603.5. Types that are local to one file only can be declared inside that file.
761
762
7633.6. Implicit conversion is generally allowed.
764
765 Implicit conversion between integer and floating point numbers can cause problems and
766 should be avoided.
767
768 Implicit conversion in single-argument constructor is usually undesirable. Therefore, all
769 single-argument constructors should be marked 'explicit', unless implicit conversion is
770 desirable. In that case, a comment should document the reason.
771
772 Avoid C-style casts. Use ``static_cast``, ``dynamic_cast``, ``reinterpret_cast``,
773 ``const_cast`` instead where appropriate. Use ``static_pointer_cast``,
774 ``dynamic_pointer_cast``, ``const_pointer_cast`` when dealing with ``shared_ptr``.
775
776
7773.7. Variables should be initialized where they are declared.
778
779 This ensures that variables are valid at any time. Sometimes it is impossible to
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500780 initialize a variable to a valid value where it is declared.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700781
782 .. code-block:: c++
783
784 int x, y, z;
785 getCenter(&x, &y, &z);
786
787 In these cases it should be left uninitialized rather than initialized to some phony
788 value.
789
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05007903.8. In most cases, class data members should not be declared ``public``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700791
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500792 Public data members violate the concepts of information hiding and encapsulation.
793 Use private variables and public accessor methods instead.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700794
795 Exceptions to this rule:
796
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500797 * When the class is essentially a dumb data structure with no or minimal behavior
798 (equivalent to a C struct, also known as POD type). In this case it is appropriate
799 to make the instance variables public by using ``struct``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700800
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500801 * When the class is used only inside the compilation unit, e.g., when implementing pImpl
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700802 idiom (aka Bridge pattern) or similar cases.
803
804
8053.9. C++ pointers and references should have their reference symbol next to the type rather
806than to the name.
807
808 .. code-block:: c++
809
810 float* x; // NOT: float *x;
811 int& y; // NOT: int &y;
812
8133.10. Implicit test for 0 should not be used other than for boolean variables and pointers.
814
815 .. code-block:: c++
816
817 if (nLines != 0) // NOT: if (nLines)
818 if (value != 0.0) // NOT: if (value)
819
Davide Pesaventobbca1b92015-12-25 20:06:00 +01008203.11. *(removed)*
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700821
8223.12. Loop variables should be initialized immediately before the loop.
823
824 .. code-block:: c++
825
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500826 bool isDone = false; // NOT: bool isDone = false;
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700827 while (!isDone) { // // other stuff
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500828 ... // while (!isDone) {
829 } // ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700830 // }
831
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05008323.13. The form ``while (true)`` should be used for infinite loops.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700833
834 .. code-block:: c++
835
836 while (true) {
837 ...
838 }
839
840 // NOT:
841 for (;;) { // NO!
842 :
843 }
844 while (1) { // NO!
845 :
846 }
847
8483.14. Complex conditional expressions must be avoided. Introduce temporary boolean variables
849instead.
850
851 .. code-block:: c++
852
853 bool isFinished = (elementNo < 0) || (elementNo > maxElement);
854 bool isRepeatedEntry = elementNo == lastElement;
855 if (isFinished || isRepeatedEntry) {
856 ...
857 }
858
859 // NOT:
860 // if ((elementNo < 0) || (elementNo > maxElement) || elementNo == lastElement) {
861 // ...
862 // }
863
864 By assigning boolean variables to expressions, the program gets automatic
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500865 documentation. The construction will be easier to read, debug, and maintain.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700866
8673.15. The conditional should be put on a separate line.
868
869 .. code-block:: c++
870
871 if (isDone) // NOT: if (isDone) doCleanup();
872 doCleanup();
873
874 This is for debugging purposes. When writing on a single line, it is not apparent
875 whether the test is really true or not.
876
8773.16. Assignment statements in conditionals must be avoided.
878
879 .. code-block:: c++
880
881 File* fileHandle = open(fileName, "w");
882 if (!fileHandle) {
883 ...
884 }
885
886 // NOT
887 // if (!(fileHandle = open(fileName, "w"))) {
888 // ..
889 // }
890
8913.17. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1
892should be considered declared as named constants instead.
893
894 If the number does not have an obvious meaning by itself, the readability is enhanced
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500895 by introducing a named constant instead. A different approach is to introduce a method
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700896 from which the constant can be accessed.
897
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05008983.18. Floating point literals should always be written with a decimal point, at least one
899decimal, and without omitting 0 before the decimal point.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700900
901 .. code-block:: c++
902
903 double total = 0.0; // NOT: double total = 0;
904 double someValue = 0.1; // NOT double someValue = .1;
905 double speed = 3.0e8; // NOT: double speed = 3e8;
906 double sum;
907 ...
908 sum = (a + b) * 10.0;
909
9103.19. ``goto`` should not be used.
911
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500912 ``goto`` statements violate the idea of structured code. Only in very few cases (for
913 instance, breaking out of deeply nested structures) should ``goto`` be considered,
914 and only if the alternative structured counterpart is proven to be less readable.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700915
Junxiao Shi03b15b32014-10-30 21:10:25 -07009163.20. ``nullptr`` should be used to represent a null pointer, instead of "0" or "NULL".
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700917
9183.21. Logical units within a block should be separated by one blank line.
919
920 .. code-block:: c++
921
922 Matrix4x4 matrix = new Matrix4x4();
923
924 double cosAngle = Math.cos(angle);
925 double sinAngle = Math.sin(angle);
926
927 matrix.setElement(1, 1, cosAngle);
928 matrix.setElement(1, 2, sinAngle);
929 matrix.setElement(2, 1, -sinAngle);
930 matrix.setElement(2, 2, cosAngle);
931
932 multiply(matrix);
933
934 Enhance readability by introducing white space between logical units of a block.
935
9363.22. Variables in declarations can be left aligned.
937
938 .. code-block:: c++
939
940 AsciiFile* file;
941 int nPoints;
942 float x, y;
943
944 Enhance readability. The variables are easier to spot from the types by alignment.
945
9463.23. Use alignment wherever it enhances readability.
947
948 .. code-block:: c++
949
950 value = (potential * oilDensity) / constant1 +
951 (depth * waterDensity) / constant2 +
952 (zCoordinateValue * gasDensity) / constant3;
953
954 minPosition = computeDistance(min, x, y, z);
955 averagePosition = computeDistance(average, x, y, z);
956
957 There are a number of places in the code where white space can be included to enhance
958 readability even if this violates common guidelines. Many of these cases have to do
959 with code alignment. General guidelines on code alignment are difficult to give, but
960 the examples above should give a general clue.
961
9623.24. All comments should be written in English.
963
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500964 In an international environment, English is the preferred language.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700965
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07009663.25. Use ``//`` for all comments, including multi-line comments.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700967
968 .. code-block:: c++
969
970 // Comment spanning
971 // more than one line.
972
973 Since multilevel C-commenting is not supported, using ``//`` comments ensure that it
974 is always possible to comment out entire sections of a file using ``/* */`` for
975 debugging purposes etc.
976
977 There should be a space between the ``//`` and the actual comment, and comments should
978 always start with an upper case letter and end with a period.
979
980 However, method and class documentation comments should use ``/** */`` style for
Junxiao Shibd2cedb2017-07-05 18:51:52 +0000981 Doxygen, JavaDoc and JSDoc. License boilerplate should use ``/* */`` style.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700982
9833.26. Comments should be included relative to their position in the code.
984
985 .. code-block:: c++
986
987 while (true) {
988 // Do something
989 something();
990 }
991
992 // NOT:
993 while (true) {
994 // Do something
995 something();
996 }
997
998 This is to avoid that the comments break the logical structure of the program.
Junxiao Shiae61aac2014-11-04 14:57:38 -0700999
10003.27. Use ``BOOST_ASSERT`` and ``BOOST_ASSERT_MSG`` for runtime assertions.
1001
1002 .. code-block:: c++
1003
1004 int x = 1;
1005 int y = 2;
1006 int z = x + y;
1007 BOOST_ASSERT(z - y == x);
1008
1009 The expression passed to ``BOOST_ASSERT`` MUST NOT have side effects,
1010 because it MAY NOT be evaluated in release builds.
1011
10123.28. Use ``static_assert`` for static assertions.
1013
Junxiao Shiae61aac2014-11-04 14:57:38 -07001014 .. code-block:: c++
1015
1016 class BaseClass
1017 {
1018 };
1019
1020 class DerivedClass : public BaseClass
1021 {
1022 };
1023
1024 static_assert(std::is_base_of<BaseClass, DerivedClass>::value,
1025 "DerivedClass must inherit from BaseClass");
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001026
10273.29. ``auto`` type specifier MAY be used for local variables, if a human reader
1028 can easily deduce the actual type.
1029
1030 .. code-block:: c++
1031
1032 std::vector<int> intVector;
1033 auto i = intVector.find(4);
1034
1035 auto stringSet = std::make_shared<std::set<std::string>>();
1036
1037 ``auto`` SHOULD NOT be used if a human reader cannot easily deduce the actual type.
1038
1039 .. code-block:: c++
1040
1041 auto x = foo(); // BAD if the declaration of foo() isn't nearby
1042
1043 ``const auto&`` SHOULD be used to represent constant reference types.
1044 ``auto&&`` SHOULD be used to represent mutable reference types.
1045
1046 .. code-block:: c++
1047
1048 std::list<std::string> strings;
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001049 for (const auto& str : strings) {
1050 statements; // cannot modify `str`
1051 }
1052 for (auto&& str : strings) {
1053 statements; // can modify `str`
1054 }
Junxiao Shia76bbc92015-03-23 11:05:37 -07001055
Davide Pesaventode2a1c22016-12-11 15:46:13 -050010563.30. Use the ``override`` or ``final`` specifier when overriding a virtual
1057member function or a virtual destructor.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001058
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001059 ``virtual`` MUST NOT be used along with ``final``, so that the compiler
1060 can generate an error when a final function does not override.
1061
1062 ``virtual`` SHOULD NOT be used along with ``override``, for consistency
1063 with ``final``.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001064
1065 .. code-block:: c++
1066
1067 class Stream
1068 {
1069 public:
1070 virtual void
1071 open();
1072 };
1073
1074 class InputStream : public Stream
1075 {
1076 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001077 void
Junxiao Shia76bbc92015-03-23 11:05:37 -07001078 open() override;
1079 };
1080
1081 class Console : public InputStream
1082 {
1083 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001084 void
1085 open() final;
Junxiao Shia76bbc92015-03-23 11:05:37 -07001086 };
1087
Spyridon Mastorakis0d2ed2e2015-07-27 19:09:12 -070010883.31. The recommended way to throw an exception derived from ``std::exception`` is to use
1089the ``BOOST_THROW_EXCEPTION``
Davide Pesavento844b0932018-05-07 01:00:16 -04001090`macro <https://www.boost.org/doc/libs/1_58_0/libs/exception/doc/BOOST_THROW_EXCEPTION.html>`__.
Davide Pesaventobbca1b92015-12-25 20:06:00 +01001091Exceptions thrown using this macro will be augmented with additional diagnostic information,
1092including file name, line number, and function name from where the exception was thrown.