blob: 8f40ba45126132d25c115fa9bf1a021879d39174 [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
55 Note that code inside namespace is **not** indented. Avoid following:
56
57 .. code-block:: c++
58
59 // NOT
60 //
61 // namespace example {
62 //
63 // code;
64 // moreCode;
65 //
66 // } // namespace example
67
681.4. The class declarations should have the following form:
69
70 .. code-block:: c++
71
72 class SomeClass : public BaseClass
73 {
74 public:
75 ... <public methods> ...
76 protected:
77 ... <protected methods> ...
78 private:
79 ... <private methods> ...
80
81 public:
82 ... <public data> ...
83 protected:
84 ... <protected data> ...
85 private:
86 ... <private data> ...
87 };
88
89 ``public``, ``protected``, ``private`` may be repeated several times without
90 interleaving (e.g., public, public, public, private, private) if this allows better
91 readability of the code.
92
93 Nested classes can be defined in appropriate visibility section, either in methods
94 block, data block, or in a separate section (depending which one provides better code
95 readability).
96
971.5. Method and function definitions should have the following form:
98
99 .. code-block:: c++
100
101 void
102 someMethod()
103 {
104 ...
105 }
106
107 void
108 SomeClass::someMethod()
109 {
110 ...
111 }
112
1131.6. The ``if-else`` class of statements should have the following form:
114
115 .. code-block:: c++
116
117 if (condition) {
118 statements;
119 }
120
121 if (condition) {
122 statements;
123 }
124 else {
125 statements;
126 }
127
128 if (condition) {
129 statements;
130 }
131 else if (condition) {
132 statements;
133 }
134 else {
135 statements;
136 }
137
138 or (less preferred):
139
140 .. code-block:: c++
141
142 if (condition)
143 {
144 statements;
145 }
146 else if (condition)
147 {
148 statements;
149 }
150 else
151 {
152 statements;
153 }
154
1551.7. A ``for`` statement should have the following form:
156
157 .. code-block:: c++
158
159 for (initialization; condition; update) {
160 statements;
161 }
162
163 or (less preferred):
164
165 .. code-block:: c++
166
167 for (initialization; condition; update)
168 {
169 statements;
170 }
171
172 An empty for statement should have the following form:
173
174 .. code-block:: c++
175
176 for (initialization; condition; update)
177 ;
178
179 This emphasizes the fact that the for statement is empty and it makes it obvious for
180 the reader that this is intentional. Empty loops should be avoided however.
181
1821.8. A ``while`` statement should have the following form:
183
184 .. code-block:: c++
185
186 while (condition) {
187 statements;
188 }
189
190 or (less preferred):
191
192 .. code-block:: c++
193
194 while (condition)
195 {
196 statements;
197 }
198
1991.9. A ``do-while`` statement should have the following form:
200
201 .. code-block:: c++
202
203 do {
204 statements;
205 } while (condition);
206
2071.10. A ``switch`` statement should have the following form:
208
209 .. code-block:: c++
210
211 switch (condition) {
Wentao Shang3aa4f412015-08-18 21:12:50 -0700212 case ABC: // 2 space indent
213 statements; // 4 space indent
214 // Fallthrough
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700215
Wentao Shang3aa4f412015-08-18 21:12:50 -0700216 case DEF:
217 statements;
218 break;
219
220 case XYZ: {
221 statements;
222 break;
223 }
224
225 default:
226 statements;
227 break;
228 }
229
230 When curly braces are used inside a ``case`` block, the braces must cover the entire
231 ``case`` block.
232
233 .. code-block:: c++
234
235 switch (condition) {
236 // Correct style
237 case A0: {
238 statements;
239 break;
240 }
241
242 // Correct style
243 case A1: {
244 statements;
245 // Fallthrough
246 }
247
248 // Incorrect style: braces should cover the entire case block
249 case B: {
250 statements;
251 }
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700252 statements;
253 break;
254
Wentao Shang3aa4f412015-08-18 21:12:50 -0700255 default:
256 break;
257 }
258
259 The following style is still allowed when none of the ``case`` blocks has curly braces.
260
261 .. code-block:: c++
262
263 switch (condition) {
264 case ABC: // no indent
265 statements; // 2 space indent
266 // Fallthrough
267
268 case DEF:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700269 statements;
270 break;
271
272 default:
273 statements;
274 break;
275 }
276
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700277 The explicit ``Fallthrough`` comment should be included whenever there is a case
278 statement without a break statement. Leaving the break out is a common error, and it
279 must be made clear that it is intentional when it is not there.
280
2811.11. A ``try-catch`` statement should have the following form:
282
283 .. code-block:: c++
284
285 try {
286 statements;
287 }
Davide Pesaventocd183d22015-09-23 16:40:28 +0200288 catch (const Exception& exception) {
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700289 statements;
290 }
291
292 or (less preferred):
293
294 .. code-block:: c++
295
296 try
297 {
298 statements;
299 }
Davide Pesaventocd183d22015-09-23 16:40:28 +0200300 catch (const Exception& exception)
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700301 {
302 statements;
303 }
304
3051.12. The incompleteness of split lines must be made obvious.
306
307 .. code-block:: c++
308
309 totalSum = a + b + c +
310 d + e;
311 function(param1, param2,
312 param3);
313 for (int tableNo = 0; tableNo < nTables;
314 tableNo += tableStep) {
315 ...
316 }
317
318 Split lines occurs when a statement exceed the 80 column limit given above. It is
319 difficult to give rigid rules for how lines should be split, but the examples above should
320 give a general hint.In general:
321
322 * Break after a comma.
323 * Break after an operator.
324 * Align the new line with the beginning of the expression on the previous line.
325
326 Exceptions:
327
328 * The following is the standard practice with operator<<:
329
330 .. code-block:: c++
331
332 std::cout << "Something here "
333 << "Something there" << std::endl;
334
3351.13. When class variables need to be initialized in the constructor, the initialization
336should take the following form:
337
338 .. code-block:: c++
339
340 SomeClass::SomeClass(int value, const std::string& string)
341 : m_value(value)
342 , m_string(string)
343 ...
344 {
345 }
346
347 Each initialization should be put on a separate line, starting either with the colon
348 for the first initialization or with comma for all subsequent initializations.
349
Junxiao Shi45c13842014-11-02 15:36:04 -07003501.14. A range-based ``for`` statement should have the following form:
351
352 .. code-block:: c++
353
354 for (T i : range) {
355 statements;
356 }
357
Junxiao Shicf698182014-11-03 08:37:42 -07003581.15. A lambda expression should have the following form:
359
360 .. code-block:: c++
361
362 [&capture1, capture2] (T1 arg1, T2 arg2) {
363 statements;
364 }
365
366 [&capture1, capture2] (T1 arg1, T2 arg2) mutable {
367 statements;
368 }
369
370 [this] (T arg) {
371 statements;
372 }
373
374 If the function has no parameters, ``()`` should be omitted.
375
376 .. code-block:: c++
377
378 [&capture1, capture2] {
379 statements;
380 }
381
382 Capture-all (``[&]`` and ``[=]``) is permitted, but its usage should be minimized.
383 Only use capture-all when it significantly simplifies code and improves readability.
384
385 .. code-block:: c++
386
387 [&] (T arg) {
388 statements;
389 }
390
391 [=] (T arg) {
392 statements;
393 }
394
395 Trailing return type should be omitted. Write them only when compiler cannot deduce
396 return type automatically, or when it improves readability.
397 ``()`` is required by C++ standard when trailing return type is written.
398
399 .. code-block:: c++
400
401 [] (T arg) -> int {
402 statements;
403 }
404
405 [] () -> int {
406 statements;
407 }
408
409 If the function body has only one line, and the whole lambda expression can fit in one line,
410 the following form is also acceptable:
411
412 .. code-block:: c++
413
414 [&capture1, capture2] (T1 arg1, T2 arg2) { statement; }
415
416 No-op can be written in a more compact form:
417
418 .. code-block:: c++
419
420 []{}
421
Junxiao Shi8b12a5a2014-11-25 10:42:47 -07004221.16. List initialization should have the following form:
423
424 .. code-block:: c++
425
426 T object{arg1, arg2};
427
428 T{arg1, arg2};
429
430 new T{arg1, arg2};
431
432 return {arg1, arg2};
433
434 function({arg1, arg2}, otherArgument);
435
436 object[{arg1, arg2}];
437
438 T({arg1, arg2})
439
440 class Class
441 {
442 private:
Davide Pesaventoe6e6fde2016-04-16 14:44:45 +0200443 T m_member = {arg1, arg2};
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700444 static T s_member = {arg1, arg2};
445 };
446
447 Class::Class()
448 : m_member{arg1, arg2}
449 {
450 }
451
452 T object = {arg1, arg2};
453
454 An empty braced-init-list is written as ``{}``. For example:
455
456 .. code-block:: c++
457
458 T object{};
459
460 T object = {};
461
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07004622. Naming Conventions
463---------------------
464
4652.1. C++ header files should have the extension ``.hpp``. Source files should have the
466extension ``.cpp``
467
468 File names should be all lower case. If the class name
469 is a composite of several words, each word in a file name should be separated with a
470 dash (-). A class should be declared in a header file and defined in a source file
471 where the name of the files match the name of the class.
472
473 ::
474
475 my-class.hpp, my-class.cpp
476
477
4782.2. Names representing types must be written in English in mixed case starting with upper case.
479
480 .. code-block:: c++
481
482 class MyClass;
483 class Line;
484 class SavingsAccount;
485
4862.3. Variable names must be written in English in mixed case starting with lower case.
487
488 .. code-block:: c++
489
490 MyClass myClass;
491 Line line;
492 SavingsAccount savingsAccount;
493 int theAnswerToLifeTheUniverseAndEverything;
494
4952.4. Named constants (including enumeration values) must be all uppercase using underscore
496to separate words.
497
498 .. code-block:: c++
499
500 const int MAX_ITERATIONS = 25;
501 const std::string COLOR_RED = "red";
502 static const double PI = 3.14;
503
504 In some cases, it is a better (or is the only way for complex constants in header-only
505 classes) to implement the value as a method:
506
507 .. code-block:: c++
508
509 int
510 getMaxIterations()
511 {
512 return 25;
513 }
514
5152.5. Names representing methods or functions must be commands starting with a verb and
516written in mixed case starting with lower case.
517
518 .. code-block:: c++
519
520 std::string
521 getName()
522 {
523 ...
524 }
525
526 double
527 computeTotalWidth()
528 {
529 ...
530 }
531
5322.6. Names representing namespaces should be all lowercase.
533
534 .. code-block:: c++
535
536 namespace model {
537 namespace analyzer {
538
539 ...
540
541 } // namespace analyzer
542 } // namespace model
543
5442.7. Names representing generic template types should be a single uppercase letter
545
546 .. code-block:: c++
547
548 template<class T> ...
549 template<class C, class D> ...
550
551 However, when template parameter represents a certain concept and expected to have a
552 certain interface, the name should be explicitly spelled out:
553
554 .. code-block:: c++
555
556 template<class FaceBase> ...
557 template<class Packet> ...
558
5592.8. Abbreviations and acronyms must not be uppercase when used as name.
560
561 .. code-block:: c++
562
563 exportHtmlSource(); // NOT: exportHTMLSource();
564 openDvdPlayer(); // NOT: openDVDPlayer();
565
5662.9. Global variables should have ``g_`` prefix
567
568 .. code-block:: c++
569
570 g_mainWindow.open();
571 g_applicationContext.getName();
572
573 In general, the use of global variables should be avoided. Consider using singleton
574 objects instead.
575
5762.10. Private class variables should have ``m_`` prefix. Static class variables should have
577``s_`` prefix.
578
579 .. code-block:: c++
580
581 class SomeClass
582 {
583 private:
584 int m_length;
585
586 static std::string s_name;
587 };
588
589
5902.11. Variables with a large scope should have long (explicit) names, variables with a small
591scope can have short names.
592
593 Scratch variables used for temporary storage or indices are best kept short. A
594 programmer reading such variables should be able to assume that its value is not used
595 outside of a few lines of code. Common scratch variables for integers are ``i``,
596 ``j``, ``k``, ``m``, ``n`` and for characters ``c`` and ``d``.
597
5982.12. The name of the object is implicit, and should be avoided in a method name.
599
600 .. code-block:: c++
601
602 line.getLength(); // NOT: line.getLineLength();
603
604 The latter seems natural in the class declaration, but proves superfluous in use, as
605 shown in the example.
606
6072.13. The terms ``get/set`` must be used where an attribute is accessed directly.
608
609 .. code-block:: c++
610
611 employee.getName();
612 employee.setName(name);
613
614 matrix.getElement(2, 4);
615 matrix.setElement(2, 4, value);
616
6172.14. The term ``compute`` can be used in methods where something is computed.
618
619 .. code-block:: c++
620
621 valueSet.computeAverage();
622 matrix.computeInverse()
623
624 Give the reader the immediate clue that this is a potentially time-consuming operation,
625 and if used repeatedly, he might consider caching the result. Consistent use of the term
626 enhances readability.
627
6282.15. The term ``find`` can be used in methods where something is looked up.
629
630 .. code-block:: c++
631
632 vertex.findNearestVertex();
633 matrix.findMinElement();
634
635 Give the reader the immediate clue that this is a simple look up method with a minimum
636 of computations involved. Consistent use of the term enhances readability.
637
6382.16. Plural form should be used on names representing a collection of objects.
639
640 .. code-block:: c++
641
642 vector<Point> points;
643 int values[];
644
645 Enhances readability since the name gives the user an immediate clue of the type of
646 the variable and the operations that can be performed on its elements.
647
6482.17. The prefix ``n`` should be used for variables representing a number of objects.
649
650 .. code-block:: c++
651
652 nPoints, nLines
653
654 The notation is taken from mathematics where it is an established convention for
655 indicating a number of objects.
656
657
6582.18. The suffix ``No`` should be used for variables representing an entity number.
659
660 .. code-block:: c++
661
662 tableNo, employeeNo
663
664 The notation is taken from mathematics where it is an established convention for
665 indicating an entity number. An elegant alternative is to prefix such variables with
666 an ``i``: ``iTable``, ``iEmployee``. This effectively makes them named iterators.
667
6682.19. The prefix ``is``, ``has``, ``need``, or similar should be used for boolean variables and
669methods.
670
671 .. code-block:: c++
672
673 isSet, isVisible, isFinished, isFound, isOpen
674 needToConvert, needToFinish
675
6762.20. Complement names must be used for complement operations, reducing complexity by
677symmetry.
678
679 ::
680
681 get/set, add/remove, create/destroy, start/stop, insert/delete,
682 increment/decrement, old/new, begin/end, first/last, up/down, min/max,
683 next/previous (and commonly used next/prev), open/close, show/hide,
684 suspend/resume, etc.
685
686 Pair ``insert/erase`` should be preferred. ``insert/delete`` can also be used if it
687 does not conflict with C++ delete keyword.
688
6892.21. Variable names should not include reference to variable type (do not use Hungarian
690notation).
691
692 .. code-block:: c++
693
694 Line* line; // NOT: Line* pLine;
695 // NOT: Line* linePtr;
696
697 size_t nPoints; // NOT lnPoints
698
699 char* name; // NOT szName
700
7012.22. Negated boolean variable names should be avoided.
702
703 .. code-block:: c++
704
705 bool isError; // NOT: isNoError
706 bool isFound; // NOT: isNotFound
707
7082.23. Enumeration constants recommended to prefix with a common type name.
709
710 .. code-block:: c++
711
712 enum Color {
713 COLOR_RED,
714 COLOR_GREEN,
715 COLOR_BLUE
716 };
717
7182.24. Exceptions can be suffixed with either ``Exception`` (e.g., ``SecurityException``) or
719``Error`` (e.g., ``SecurityError``).
720
721 The recommended method is to declare exception class ``Exception`` or ``Error`` as an
722 inner class, from which the exception is thrown. For example, when declaring class
723 ``Foo`` that can throw errors, one can write the following:
724
725 .. code-block:: c++
726
727 #include <stdexcept>
728
729 class Foo
730 {
731 class Error : public std::runtime_error
732 {
733 public:
734 explicit
735 Error(const std::string& what)
736 : std::runtime_error(what)
737 {
738 }
739 };
740 };
741
742 In addition to that, if class Foo is a base class or interface for some class
743 hierarchy, then child classes should should define their own ``Error`` or
744 ``Exception`` classes that are inherited from the parent's Error class.
745
746
7472.25. Functions (methods returning something) should be named after what they return and
748procedures (void methods) after what they do.
749
750 Increase readability. Makes it clear what the unit should do and especially all the
751 things it is not supposed to do. This again makes it easier to keep the code clean of
752 side effects.
753
7543. Miscellaneous
755----------------
756
7573.1. Exceptions can be used in the code, but should be used only in exceptional cases and
758not in the primary processing path.
759
7603.2. Header files must contain an include guard.
761
762 For example, header file located in ``module/class-name.hpp`` or in
763 ``src/module/class-name.hpp`` should have header guard in the following form:
764
765 .. code-block:: c++
766
767 #ifndef APP_MODULE_CLASS_NAME_HPP
768 #define APP_MODULE_CLASS_NAME_HPP
769 ...
770 #endif // APP_MODULE_CLASS_NAME_HPP
771
772 The name should follow the location of the file inside the source tree and prevents
773 naming conflicts. Header guard should be prefixed with the application/library name
774 to avoid conflicts with other packaged and libraries.
775
7763.3. Header files which are in the same source distribution should be included in
777``"quotes"``, if possible with a path relative to the source file. Header files for
778system and other external libraries should be included in ``<angle brackets>``.
779
780 .. code-block:: c++
781
782 #include <string>
783 #include <boost/lexical_cast.hpp>
784
785 #include "util/random.hpp"
786
7873.4. Include statements should be sorted and grouped. Sorted by their hierarchical position
788in the system with low level files included first. Leave an empty line between groups
789of include statements.
790
791 .. code-block:: c++
792
793 #include <fstream>
794 #include <iomanip>
795
796 #include <boost/lexical_cast.hpp>
797 #include <boost/regex.hpp>
798
799 #include "detail/pending-interest.hpp"
800 #include "util/random.hpp"
801
802
8033.5. Types that are local to one file only can be declared inside that file.
804
805
8063.6. Implicit conversion is generally allowed.
807
808 Implicit conversion between integer and floating point numbers can cause problems and
809 should be avoided.
810
811 Implicit conversion in single-argument constructor is usually undesirable. Therefore, all
812 single-argument constructors should be marked 'explicit', unless implicit conversion is
813 desirable. In that case, a comment should document the reason.
814
815 Avoid C-style casts. Use ``static_cast``, ``dynamic_cast``, ``reinterpret_cast``,
816 ``const_cast`` instead where appropriate. Use ``static_pointer_cast``,
817 ``dynamic_pointer_cast``, ``const_pointer_cast`` when dealing with ``shared_ptr``.
818
819
8203.7. Variables should be initialized where they are declared.
821
822 This ensures that variables are valid at any time. Sometimes it is impossible to
823 initialize a variable to a valid value where it is declared:
824
825 .. code-block:: c++
826
827 int x, y, z;
828 getCenter(&x, &y, &z);
829
830 In these cases it should be left uninitialized rather than initialized to some phony
831 value.
832
8333.8. In most cases, class instance variables should not be declared public.
834
835 The concepts of information hiding and encapsulation are violated by public variables. Use
836 private variables and access methods instead.
837
838 Exceptions to this rule:
839
840 * when the class is essentially a dumb data structure with no or minimal behavior
841 (equivalent to a C struct, also known as PODS). In this case it is appropriate to make
842 the instance variables public by using struct.
843
844 * when the class is used only inside the compilation unit, e.g., when implementing pImpl
845 idiom (aka Bridge pattern) or similar cases.
846
847
8483.9. C++ pointers and references should have their reference symbol next to the type rather
849than to the name.
850
851 .. code-block:: c++
852
853 float* x; // NOT: float *x;
854 int& y; // NOT: int &y;
855
8563.10. Implicit test for 0 should not be used other than for boolean variables and pointers.
857
858 .. code-block:: c++
859
860 if (nLines != 0) // NOT: if (nLines)
861 if (value != 0.0) // NOT: if (value)
862
Davide Pesaventobbca1b92015-12-25 20:06:00 +01008633.11. *(removed)*
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700864
8653.12. Loop variables should be initialized immediately before the loop.
866
867 .. code-block:: c++
868
869 isDone = false; // NOT: bool isDone = false;
870 while (!isDone) { // // other stuff
871 : // while (!isDone) {
872 } // :
873 // }
874
8753.13. The form while (true) should be used for infinite loops.
876
877 .. code-block:: c++
878
879 while (true) {
880 ...
881 }
882
883 // NOT:
884 for (;;) { // NO!
885 :
886 }
887 while (1) { // NO!
888 :
889 }
890
8913.14. Complex conditional expressions must be avoided. Introduce temporary boolean variables
892instead.
893
894 .. code-block:: c++
895
896 bool isFinished = (elementNo < 0) || (elementNo > maxElement);
897 bool isRepeatedEntry = elementNo == lastElement;
898 if (isFinished || isRepeatedEntry) {
899 ...
900 }
901
902 // NOT:
903 // if ((elementNo < 0) || (elementNo > maxElement) || elementNo == lastElement) {
904 // ...
905 // }
906
907 By assigning boolean variables to expressions, the program gets automatic
908 documentation. The construction will be easier to read, debug and maintain.
909
9103.15. The conditional should be put on a separate line.
911
912 .. code-block:: c++
913
914 if (isDone) // NOT: if (isDone) doCleanup();
915 doCleanup();
916
917 This is for debugging purposes. When writing on a single line, it is not apparent
918 whether the test is really true or not.
919
9203.16. Assignment statements in conditionals must be avoided.
921
922 .. code-block:: c++
923
924 File* fileHandle = open(fileName, "w");
925 if (!fileHandle) {
926 ...
927 }
928
929 // NOT
930 // if (!(fileHandle = open(fileName, "w"))) {
931 // ..
932 // }
933
9343.17. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1
935should be considered declared as named constants instead.
936
937 If the number does not have an obvious meaning by itself, the readability is enhanced
938 by introducing a named constant instead. A different approach is to introduce a method
939 from which the constant can be accessed.
940
9413.18. Floating point constants should always be written with decimal point, at least one
942 decimal, and without omitting 0 before decimal point.
943
944 .. code-block:: c++
945
946 double total = 0.0; // NOT: double total = 0;
947 double someValue = 0.1; // NOT double someValue = .1;
948 double speed = 3.0e8; // NOT: double speed = 3e8;
949 double sum;
950 ...
951 sum = (a + b) * 10.0;
952
9533.19. ``goto`` should not be used.
954
955Goto statements violate the idea of structured code. Only in some very few cases (for
956instance breaking out of deeply nested structures) should goto be considered, and only if
957the alternative structured counterpart is proven to be less readable.
958
Junxiao Shi03b15b32014-10-30 21:10:25 -07009593.20. ``nullptr`` should be used to represent a null pointer, instead of "0" or "NULL".
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700960
9613.21. Logical units within a block should be separated by one blank line.
962
963 .. code-block:: c++
964
965 Matrix4x4 matrix = new Matrix4x4();
966
967 double cosAngle = Math.cos(angle);
968 double sinAngle = Math.sin(angle);
969
970 matrix.setElement(1, 1, cosAngle);
971 matrix.setElement(1, 2, sinAngle);
972 matrix.setElement(2, 1, -sinAngle);
973 matrix.setElement(2, 2, cosAngle);
974
975 multiply(matrix);
976
977 Enhance readability by introducing white space between logical units of a block.
978
9793.22. Variables in declarations can be left aligned.
980
981 .. code-block:: c++
982
983 AsciiFile* file;
984 int nPoints;
985 float x, y;
986
987 Enhance readability. The variables are easier to spot from the types by alignment.
988
9893.23. Use alignment wherever it enhances readability.
990
991 .. code-block:: c++
992
993 value = (potential * oilDensity) / constant1 +
994 (depth * waterDensity) / constant2 +
995 (zCoordinateValue * gasDensity) / constant3;
996
997 minPosition = computeDistance(min, x, y, z);
998 averagePosition = computeDistance(average, x, y, z);
999
1000 There are a number of places in the code where white space can be included to enhance
1001 readability even if this violates common guidelines. Many of these cases have to do
1002 with code alignment. General guidelines on code alignment are difficult to give, but
1003 the examples above should give a general clue.
1004
10053.24. All comments should be written in English.
1006
1007 In an international environment English is the preferred language.
1008
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070010093.25. Use ``//`` for all comments, including multi-line comments.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07001010
1011 .. code-block:: c++
1012
1013 // Comment spanning
1014 // more than one line.
1015
1016 Since multilevel C-commenting is not supported, using ``//`` comments ensure that it
1017 is always possible to comment out entire sections of a file using ``/* */`` for
1018 debugging purposes etc.
1019
1020 There should be a space between the ``//`` and the actual comment, and comments should
1021 always start with an upper case letter and end with a period.
1022
1023 However, method and class documentation comments should use ``/** */`` style for
1024 Doxygen, JavaDoc and JSDoc.
1025
10263.26. Comments should be included relative to their position in the code.
1027
1028 .. code-block:: c++
1029
1030 while (true) {
1031 // Do something
1032 something();
1033 }
1034
1035 // NOT:
1036 while (true) {
1037 // Do something
1038 something();
1039 }
1040
1041 This is to avoid that the comments break the logical structure of the program.
Junxiao Shiae61aac2014-11-04 14:57:38 -07001042
10433.27. Use ``BOOST_ASSERT`` and ``BOOST_ASSERT_MSG`` for runtime assertions.
1044
1045 .. code-block:: c++
1046
1047 int x = 1;
1048 int y = 2;
1049 int z = x + y;
1050 BOOST_ASSERT(z - y == x);
1051
1052 The expression passed to ``BOOST_ASSERT`` MUST NOT have side effects,
1053 because it MAY NOT be evaluated in release builds.
1054
10553.28. Use ``static_assert`` for static assertions.
1056
Junxiao Shiae61aac2014-11-04 14:57:38 -07001057 .. code-block:: c++
1058
1059 class BaseClass
1060 {
1061 };
1062
1063 class DerivedClass : public BaseClass
1064 {
1065 };
1066
1067 static_assert(std::is_base_of<BaseClass, DerivedClass>::value,
1068 "DerivedClass must inherit from BaseClass");
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001069
10703.29. ``auto`` type specifier MAY be used for local variables, if a human reader
1071 can easily deduce the actual type.
1072
1073 .. code-block:: c++
1074
1075 std::vector<int> intVector;
1076 auto i = intVector.find(4);
1077
1078 auto stringSet = std::make_shared<std::set<std::string>>();
1079
1080 ``auto`` SHOULD NOT be used if a human reader cannot easily deduce the actual type.
1081
1082 .. code-block:: c++
1083
1084 auto x = foo(); // BAD if the declaration of foo() isn't nearby
1085
1086 ``const auto&`` SHOULD be used to represent constant reference types.
1087 ``auto&&`` SHOULD be used to represent mutable reference types.
1088
1089 .. code-block:: c++
1090
1091 std::list<std::string> strings;
1092
1093 for (const auto& str : strings) {
1094 statements; // cannot modify `str`
1095 }
1096 for (auto&& str : strings) {
1097 statements; // can modify `str`
1098 }
Junxiao Shia76bbc92015-03-23 11:05:37 -07001099
Davide Pesaventode2a1c22016-12-11 15:46:13 -050011003.30. Use the ``override`` or ``final`` specifier when overriding a virtual
1101member function or a virtual destructor.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001102
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001103 ``virtual`` MUST NOT be used along with ``final``, so that the compiler
1104 can generate an error when a final function does not override.
1105
1106 ``virtual`` SHOULD NOT be used along with ``override``, for consistency
1107 with ``final``.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001108
1109 .. code-block:: c++
1110
1111 class Stream
1112 {
1113 public:
1114 virtual void
1115 open();
1116 };
1117
1118 class InputStream : public Stream
1119 {
1120 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001121 void
Junxiao Shia76bbc92015-03-23 11:05:37 -07001122 open() override;
1123 };
1124
1125 class Console : public InputStream
1126 {
1127 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001128 void
1129 open() final;
Junxiao Shia76bbc92015-03-23 11:05:37 -07001130 };
1131
Spyridon Mastorakis0d2ed2e2015-07-27 19:09:12 -070011323.31. The recommended way to throw an exception derived from ``std::exception`` is to use
1133the ``BOOST_THROW_EXCEPTION``
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001134`macro <http://www.boost.org/doc/libs/1_54_0/libs/exception/doc/BOOST_THROW_EXCEPTION.html>`__.
Davide Pesaventobbca1b92015-12-25 20:06:00 +01001135Exceptions thrown using this macro will be augmented with additional diagnostic information,
1136including file name, line number, and function name from where the exception was thrown.