blob: 6a578baa22740082b11a9b184eef5bf8e1a45b13 [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) {
212 case ABC:
213 statements;
214 // Fallthrough
215
216 case DEF:
217 statements;
218 break;
219
220 case XYZ:
221 statements;
222 break;
223
224 default:
225 statements;
226 break;
227 }
228
229 or (less preferred):
230
231 .. code-block:: c++
232
233 switch (condition)
234 {
235 case ABC:
236 statements;
237 // Fallthrough
238
239 case DEF:
240 statements;
241 break;
242
243 case XYZ:
244 statements;
245 break;
246
247 default:
248 statements;
249 break;
250 }
251
252 The explicit ``Fallthrough`` comment should be included whenever there is a case
253 statement without a break statement. Leaving the break out is a common error, and it
254 must be made clear that it is intentional when it is not there.
255
2561.11. A ``try-catch`` statement should have the following form:
257
258 .. code-block:: c++
259
260 try {
261 statements;
262 }
263 catch (Exception& exception) {
264 statements;
265 }
266
267 or (less preferred):
268
269 .. code-block:: c++
270
271 try
272 {
273 statements;
274 }
275 catch (Exception& exception)
276 {
277 statements;
278 }
279
2801.12. The incompleteness of split lines must be made obvious.
281
282 .. code-block:: c++
283
284 totalSum = a + b + c +
285 d + e;
286 function(param1, param2,
287 param3);
288 for (int tableNo = 0; tableNo < nTables;
289 tableNo += tableStep) {
290 ...
291 }
292
293 Split lines occurs when a statement exceed the 80 column limit given above. It is
294 difficult to give rigid rules for how lines should be split, but the examples above should
295 give a general hint.In general:
296
297 * Break after a comma.
298 * Break after an operator.
299 * Align the new line with the beginning of the expression on the previous line.
300
301 Exceptions:
302
303 * The following is the standard practice with operator<<:
304
305 .. code-block:: c++
306
307 std::cout << "Something here "
308 << "Something there" << std::endl;
309
3101.13. When class variables need to be initialized in the constructor, the initialization
311should take the following form:
312
313 .. code-block:: c++
314
315 SomeClass::SomeClass(int value, const std::string& string)
316 : m_value(value)
317 , m_string(string)
318 ...
319 {
320 }
321
322 Each initialization should be put on a separate line, starting either with the colon
323 for the first initialization or with comma for all subsequent initializations.
324
Junxiao Shi45c13842014-11-02 15:36:04 -07003251.14. A range-based ``for`` statement should have the following form:
326
327 .. code-block:: c++
328
329 for (T i : range) {
330 statements;
331 }
332
Junxiao Shicf698182014-11-03 08:37:42 -07003331.15. A lambda expression should have the following form:
334
335 .. code-block:: c++
336
337 [&capture1, capture2] (T1 arg1, T2 arg2) {
338 statements;
339 }
340
341 [&capture1, capture2] (T1 arg1, T2 arg2) mutable {
342 statements;
343 }
344
345 [this] (T arg) {
346 statements;
347 }
348
349 If the function has no parameters, ``()`` should be omitted.
350
351 .. code-block:: c++
352
353 [&capture1, capture2] {
354 statements;
355 }
356
357 Capture-all (``[&]`` and ``[=]``) is permitted, but its usage should be minimized.
358 Only use capture-all when it significantly simplifies code and improves readability.
359
360 .. code-block:: c++
361
362 [&] (T arg) {
363 statements;
364 }
365
366 [=] (T arg) {
367 statements;
368 }
369
370 Trailing return type should be omitted. Write them only when compiler cannot deduce
371 return type automatically, or when it improves readability.
372 ``()`` is required by C++ standard when trailing return type is written.
373
374 .. code-block:: c++
375
376 [] (T arg) -> int {
377 statements;
378 }
379
380 [] () -> int {
381 statements;
382 }
383
384 If the function body has only one line, and the whole lambda expression can fit in one line,
385 the following form is also acceptable:
386
387 .. code-block:: c++
388
389 [&capture1, capture2] (T1 arg1, T2 arg2) { statement; }
390
391 No-op can be written in a more compact form:
392
393 .. code-block:: c++
394
395 []{}
396
Junxiao Shi8b12a5a2014-11-25 10:42:47 -07003971.16. List initialization should have the following form:
398
399 .. code-block:: c++
400
401 T object{arg1, arg2};
402
403 T{arg1, arg2};
404
405 new T{arg1, arg2};
406
407 return {arg1, arg2};
408
409 function({arg1, arg2}, otherArgument);
410
411 object[{arg1, arg2}];
412
413 T({arg1, arg2})
414
415 class Class
416 {
417 private:
418 T m_member = {arg1, arg2}; // not supported by GCC 4.6
419 static T s_member = {arg1, arg2};
420 };
421
422 Class::Class()
423 : m_member{arg1, arg2}
424 {
425 }
426
427 T object = {arg1, arg2};
428
429 An empty braced-init-list is written as ``{}``. For example:
430
431 .. code-block:: c++
432
433 T object{};
434
435 T object = {};
436
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07004372. Naming Conventions
438---------------------
439
4402.1. C++ header files should have the extension ``.hpp``. Source files should have the
441extension ``.cpp``
442
443 File names should be all lower case. If the class name
444 is a composite of several words, each word in a file name should be separated with a
445 dash (-). A class should be declared in a header file and defined in a source file
446 where the name of the files match the name of the class.
447
448 ::
449
450 my-class.hpp, my-class.cpp
451
452
4532.2. Names representing types must be written in English in mixed case starting with upper case.
454
455 .. code-block:: c++
456
457 class MyClass;
458 class Line;
459 class SavingsAccount;
460
4612.3. Variable names must be written in English in mixed case starting with lower case.
462
463 .. code-block:: c++
464
465 MyClass myClass;
466 Line line;
467 SavingsAccount savingsAccount;
468 int theAnswerToLifeTheUniverseAndEverything;
469
4702.4. Named constants (including enumeration values) must be all uppercase using underscore
471to separate words.
472
473 .. code-block:: c++
474
475 const int MAX_ITERATIONS = 25;
476 const std::string COLOR_RED = "red";
477 static const double PI = 3.14;
478
479 In some cases, it is a better (or is the only way for complex constants in header-only
480 classes) to implement the value as a method:
481
482 .. code-block:: c++
483
484 int
485 getMaxIterations()
486 {
487 return 25;
488 }
489
4902.5. Names representing methods or functions must be commands starting with a verb and
491written in mixed case starting with lower case.
492
493 .. code-block:: c++
494
495 std::string
496 getName()
497 {
498 ...
499 }
500
501 double
502 computeTotalWidth()
503 {
504 ...
505 }
506
5072.6. Names representing namespaces should be all lowercase.
508
509 .. code-block:: c++
510
511 namespace model {
512 namespace analyzer {
513
514 ...
515
516 } // namespace analyzer
517 } // namespace model
518
5192.7. Names representing generic template types should be a single uppercase letter
520
521 .. code-block:: c++
522
523 template<class T> ...
524 template<class C, class D> ...
525
526 However, when template parameter represents a certain concept and expected to have a
527 certain interface, the name should be explicitly spelled out:
528
529 .. code-block:: c++
530
531 template<class FaceBase> ...
532 template<class Packet> ...
533
5342.8. Abbreviations and acronyms must not be uppercase when used as name.
535
536 .. code-block:: c++
537
538 exportHtmlSource(); // NOT: exportHTMLSource();
539 openDvdPlayer(); // NOT: openDVDPlayer();
540
5412.9. Global variables should have ``g_`` prefix
542
543 .. code-block:: c++
544
545 g_mainWindow.open();
546 g_applicationContext.getName();
547
548 In general, the use of global variables should be avoided. Consider using singleton
549 objects instead.
550
5512.10. Private class variables should have ``m_`` prefix. Static class variables should have
552``s_`` prefix.
553
554 .. code-block:: c++
555
556 class SomeClass
557 {
558 private:
559 int m_length;
560
561 static std::string s_name;
562 };
563
564
5652.11. Variables with a large scope should have long (explicit) names, variables with a small
566scope can have short names.
567
568 Scratch variables used for temporary storage or indices are best kept short. A
569 programmer reading such variables should be able to assume that its value is not used
570 outside of a few lines of code. Common scratch variables for integers are ``i``,
571 ``j``, ``k``, ``m``, ``n`` and for characters ``c`` and ``d``.
572
5732.12. The name of the object is implicit, and should be avoided in a method name.
574
575 .. code-block:: c++
576
577 line.getLength(); // NOT: line.getLineLength();
578
579 The latter seems natural in the class declaration, but proves superfluous in use, as
580 shown in the example.
581
5822.13. The terms ``get/set`` must be used where an attribute is accessed directly.
583
584 .. code-block:: c++
585
586 employee.getName();
587 employee.setName(name);
588
589 matrix.getElement(2, 4);
590 matrix.setElement(2, 4, value);
591
5922.14. The term ``compute`` can be used in methods where something is computed.
593
594 .. code-block:: c++
595
596 valueSet.computeAverage();
597 matrix.computeInverse()
598
599 Give the reader the immediate clue that this is a potentially time-consuming operation,
600 and if used repeatedly, he might consider caching the result. Consistent use of the term
601 enhances readability.
602
6032.15. The term ``find`` can be used in methods where something is looked up.
604
605 .. code-block:: c++
606
607 vertex.findNearestVertex();
608 matrix.findMinElement();
609
610 Give the reader the immediate clue that this is a simple look up method with a minimum
611 of computations involved. Consistent use of the term enhances readability.
612
6132.16. Plural form should be used on names representing a collection of objects.
614
615 .. code-block:: c++
616
617 vector<Point> points;
618 int values[];
619
620 Enhances readability since the name gives the user an immediate clue of the type of
621 the variable and the operations that can be performed on its elements.
622
6232.17. The prefix ``n`` should be used for variables representing a number of objects.
624
625 .. code-block:: c++
626
627 nPoints, nLines
628
629 The notation is taken from mathematics where it is an established convention for
630 indicating a number of objects.
631
632
6332.18. The suffix ``No`` should be used for variables representing an entity number.
634
635 .. code-block:: c++
636
637 tableNo, employeeNo
638
639 The notation is taken from mathematics where it is an established convention for
640 indicating an entity number. An elegant alternative is to prefix such variables with
641 an ``i``: ``iTable``, ``iEmployee``. This effectively makes them named iterators.
642
6432.19. The prefix ``is``, ``has``, ``need``, or similar should be used for boolean variables and
644methods.
645
646 .. code-block:: c++
647
648 isSet, isVisible, isFinished, isFound, isOpen
649 needToConvert, needToFinish
650
6512.20. Complement names must be used for complement operations, reducing complexity by
652symmetry.
653
654 ::
655
656 get/set, add/remove, create/destroy, start/stop, insert/delete,
657 increment/decrement, old/new, begin/end, first/last, up/down, min/max,
658 next/previous (and commonly used next/prev), open/close, show/hide,
659 suspend/resume, etc.
660
661 Pair ``insert/erase`` should be preferred. ``insert/delete`` can also be used if it
662 does not conflict with C++ delete keyword.
663
6642.21. Variable names should not include reference to variable type (do not use Hungarian
665notation).
666
667 .. code-block:: c++
668
669 Line* line; // NOT: Line* pLine;
670 // NOT: Line* linePtr;
671
672 size_t nPoints; // NOT lnPoints
673
674 char* name; // NOT szName
675
6762.22. Negated boolean variable names should be avoided.
677
678 .. code-block:: c++
679
680 bool isError; // NOT: isNoError
681 bool isFound; // NOT: isNotFound
682
6832.23. Enumeration constants recommended to prefix with a common type name.
684
685 .. code-block:: c++
686
687 enum Color {
688 COLOR_RED,
689 COLOR_GREEN,
690 COLOR_BLUE
691 };
692
6932.24. Exceptions can be suffixed with either ``Exception`` (e.g., ``SecurityException``) or
694``Error`` (e.g., ``SecurityError``).
695
696 The recommended method is to declare exception class ``Exception`` or ``Error`` as an
697 inner class, from which the exception is thrown. For example, when declaring class
698 ``Foo`` that can throw errors, one can write the following:
699
700 .. code-block:: c++
701
702 #include <stdexcept>
703
704 class Foo
705 {
706 class Error : public std::runtime_error
707 {
708 public:
709 explicit
710 Error(const std::string& what)
711 : std::runtime_error(what)
712 {
713 }
714 };
715 };
716
717 In addition to that, if class Foo is a base class or interface for some class
718 hierarchy, then child classes should should define their own ``Error`` or
719 ``Exception`` classes that are inherited from the parent's Error class.
720
721
7222.25. Functions (methods returning something) should be named after what they return and
723procedures (void methods) after what they do.
724
725 Increase readability. Makes it clear what the unit should do and especially all the
726 things it is not supposed to do. This again makes it easier to keep the code clean of
727 side effects.
728
7293. Miscellaneous
730----------------
731
7323.1. Exceptions can be used in the code, but should be used only in exceptional cases and
733not in the primary processing path.
734
7353.2. Header files must contain an include guard.
736
737 For example, header file located in ``module/class-name.hpp`` or in
738 ``src/module/class-name.hpp`` should have header guard in the following form:
739
740 .. code-block:: c++
741
742 #ifndef APP_MODULE_CLASS_NAME_HPP
743 #define APP_MODULE_CLASS_NAME_HPP
744 ...
745 #endif // APP_MODULE_CLASS_NAME_HPP
746
747 The name should follow the location of the file inside the source tree and prevents
748 naming conflicts. Header guard should be prefixed with the application/library name
749 to avoid conflicts with other packaged and libraries.
750
7513.3. Header files which are in the same source distribution should be included in
752``"quotes"``, if possible with a path relative to the source file. Header files for
753system and other external libraries should be included in ``<angle brackets>``.
754
755 .. code-block:: c++
756
757 #include <string>
758 #include <boost/lexical_cast.hpp>
759
760 #include "util/random.hpp"
761
7623.4. Include statements should be sorted and grouped. Sorted by their hierarchical position
763in the system with low level files included first. Leave an empty line between groups
764of include statements.
765
766 .. code-block:: c++
767
768 #include <fstream>
769 #include <iomanip>
770
771 #include <boost/lexical_cast.hpp>
772 #include <boost/regex.hpp>
773
774 #include "detail/pending-interest.hpp"
775 #include "util/random.hpp"
776
777
7783.5. Types that are local to one file only can be declared inside that file.
779
780
7813.6. Implicit conversion is generally allowed.
782
783 Implicit conversion between integer and floating point numbers can cause problems and
784 should be avoided.
785
786 Implicit conversion in single-argument constructor is usually undesirable. Therefore, all
787 single-argument constructors should be marked 'explicit', unless implicit conversion is
788 desirable. In that case, a comment should document the reason.
789
790 Avoid C-style casts. Use ``static_cast``, ``dynamic_cast``, ``reinterpret_cast``,
791 ``const_cast`` instead where appropriate. Use ``static_pointer_cast``,
792 ``dynamic_pointer_cast``, ``const_pointer_cast`` when dealing with ``shared_ptr``.
793
794
7953.7. Variables should be initialized where they are declared.
796
797 This ensures that variables are valid at any time. Sometimes it is impossible to
798 initialize a variable to a valid value where it is declared:
799
800 .. code-block:: c++
801
802 int x, y, z;
803 getCenter(&x, &y, &z);
804
805 In these cases it should be left uninitialized rather than initialized to some phony
806 value.
807
8083.8. In most cases, class instance variables should not be declared public.
809
810 The concepts of information hiding and encapsulation are violated by public variables. Use
811 private variables and access methods instead.
812
813 Exceptions to this rule:
814
815 * when the class is essentially a dumb data structure with no or minimal behavior
816 (equivalent to a C struct, also known as PODS). In this case it is appropriate to make
817 the instance variables public by using struct.
818
819 * when the class is used only inside the compilation unit, e.g., when implementing pImpl
820 idiom (aka Bridge pattern) or similar cases.
821
822
8233.9. C++ pointers and references should have their reference symbol next to the type rather
824than to the name.
825
826 .. code-block:: c++
827
828 float* x; // NOT: float *x;
829 int& y; // NOT: int &y;
830
8313.10. Implicit test for 0 should not be used other than for boolean variables and pointers.
832
833 .. code-block:: c++
834
835 if (nLines != 0) // NOT: if (nLines)
836 if (value != 0.0) // NOT: if (value)
837
8383.11. When checking if ``shared_ptr`` points to an object, explicit ``static_cast<bool>``
839must be used.
840
841 ``shared_ptr`` in C++11 (unlike ``boost::shared_ptr``) does not have implicit
842 conversion to bool.
843
8443.12. Loop variables should be initialized immediately before the loop.
845
846 .. code-block:: c++
847
848 isDone = false; // NOT: bool isDone = false;
849 while (!isDone) { // // other stuff
850 : // while (!isDone) {
851 } // :
852 // }
853
8543.13. The form while (true) should be used for infinite loops.
855
856 .. code-block:: c++
857
858 while (true) {
859 ...
860 }
861
862 // NOT:
863 for (;;) { // NO!
864 :
865 }
866 while (1) { // NO!
867 :
868 }
869
8703.14. Complex conditional expressions must be avoided. Introduce temporary boolean variables
871instead.
872
873 .. code-block:: c++
874
875 bool isFinished = (elementNo < 0) || (elementNo > maxElement);
876 bool isRepeatedEntry = elementNo == lastElement;
877 if (isFinished || isRepeatedEntry) {
878 ...
879 }
880
881 // NOT:
882 // if ((elementNo < 0) || (elementNo > maxElement) || elementNo == lastElement) {
883 // ...
884 // }
885
886 By assigning boolean variables to expressions, the program gets automatic
887 documentation. The construction will be easier to read, debug and maintain.
888
8893.15. The conditional should be put on a separate line.
890
891 .. code-block:: c++
892
893 if (isDone) // NOT: if (isDone) doCleanup();
894 doCleanup();
895
896 This is for debugging purposes. When writing on a single line, it is not apparent
897 whether the test is really true or not.
898
8993.16. Assignment statements in conditionals must be avoided.
900
901 .. code-block:: c++
902
903 File* fileHandle = open(fileName, "w");
904 if (!fileHandle) {
905 ...
906 }
907
908 // NOT
909 // if (!(fileHandle = open(fileName, "w"))) {
910 // ..
911 // }
912
9133.17. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1
914should be considered declared as named constants instead.
915
916 If the number does not have an obvious meaning by itself, the readability is enhanced
917 by introducing a named constant instead. A different approach is to introduce a method
918 from which the constant can be accessed.
919
9203.18. Floating point constants should always be written with decimal point, at least one
921 decimal, and without omitting 0 before decimal point.
922
923 .. code-block:: c++
924
925 double total = 0.0; // NOT: double total = 0;
926 double someValue = 0.1; // NOT double someValue = .1;
927 double speed = 3.0e8; // NOT: double speed = 3e8;
928 double sum;
929 ...
930 sum = (a + b) * 10.0;
931
9323.19. ``goto`` should not be used.
933
934Goto statements violate the idea of structured code. Only in some very few cases (for
935instance breaking out of deeply nested structures) should goto be considered, and only if
936the alternative structured counterpart is proven to be less readable.
937
Junxiao Shi03b15b32014-10-30 21:10:25 -07009383.20. ``nullptr`` should be used to represent a null pointer, instead of "0" or "NULL".
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700939
9403.21. Logical units within a block should be separated by one blank line.
941
942 .. code-block:: c++
943
944 Matrix4x4 matrix = new Matrix4x4();
945
946 double cosAngle = Math.cos(angle);
947 double sinAngle = Math.sin(angle);
948
949 matrix.setElement(1, 1, cosAngle);
950 matrix.setElement(1, 2, sinAngle);
951 matrix.setElement(2, 1, -sinAngle);
952 matrix.setElement(2, 2, cosAngle);
953
954 multiply(matrix);
955
956 Enhance readability by introducing white space between logical units of a block.
957
9583.22. Variables in declarations can be left aligned.
959
960 .. code-block:: c++
961
962 AsciiFile* file;
963 int nPoints;
964 float x, y;
965
966 Enhance readability. The variables are easier to spot from the types by alignment.
967
9683.23. Use alignment wherever it enhances readability.
969
970 .. code-block:: c++
971
972 value = (potential * oilDensity) / constant1 +
973 (depth * waterDensity) / constant2 +
974 (zCoordinateValue * gasDensity) / constant3;
975
976 minPosition = computeDistance(min, x, y, z);
977 averagePosition = computeDistance(average, x, y, z);
978
979 There are a number of places in the code where white space can be included to enhance
980 readability even if this violates common guidelines. Many of these cases have to do
981 with code alignment. General guidelines on code alignment are difficult to give, but
982 the examples above should give a general clue.
983
9843.24. All comments should be written in English.
985
986 In an international environment English is the preferred language.
987
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07009883.25. Use ``//`` for all comments, including multi-line comments.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700989
990 .. code-block:: c++
991
992 // Comment spanning
993 // more than one line.
994
995 Since multilevel C-commenting is not supported, using ``//`` comments ensure that it
996 is always possible to comment out entire sections of a file using ``/* */`` for
997 debugging purposes etc.
998
999 There should be a space between the ``//`` and the actual comment, and comments should
1000 always start with an upper case letter and end with a period.
1001
1002 However, method and class documentation comments should use ``/** */`` style for
1003 Doxygen, JavaDoc and JSDoc.
1004
10053.26. Comments should be included relative to their position in the code.
1006
1007 .. code-block:: c++
1008
1009 while (true) {
1010 // Do something
1011 something();
1012 }
1013
1014 // NOT:
1015 while (true) {
1016 // Do something
1017 something();
1018 }
1019
1020 This is to avoid that the comments break the logical structure of the program.
Junxiao Shiae61aac2014-11-04 14:57:38 -07001021
10223.27. Use ``BOOST_ASSERT`` and ``BOOST_ASSERT_MSG`` for runtime assertions.
1023
1024 .. code-block:: c++
1025
1026 int x = 1;
1027 int y = 2;
1028 int z = x + y;
1029 BOOST_ASSERT(z - y == x);
1030
1031 The expression passed to ``BOOST_ASSERT`` MUST NOT have side effects,
1032 because it MAY NOT be evaluated in release builds.
1033
10343.28. Use ``static_assert`` for static assertions.
1035
Junxiao Shiae61aac2014-11-04 14:57:38 -07001036 .. code-block:: c++
1037
1038 class BaseClass
1039 {
1040 };
1041
1042 class DerivedClass : public BaseClass
1043 {
1044 };
1045
1046 static_assert(std::is_base_of<BaseClass, DerivedClass>::value,
1047 "DerivedClass must inherit from BaseClass");
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001048
10493.29. ``auto`` type specifier MAY be used for local variables, if a human reader
1050 can easily deduce the actual type.
1051
1052 .. code-block:: c++
1053
1054 std::vector<int> intVector;
1055 auto i = intVector.find(4);
1056
1057 auto stringSet = std::make_shared<std::set<std::string>>();
1058
1059 ``auto`` SHOULD NOT be used if a human reader cannot easily deduce the actual type.
1060
1061 .. code-block:: c++
1062
1063 auto x = foo(); // BAD if the declaration of foo() isn't nearby
1064
1065 ``const auto&`` SHOULD be used to represent constant reference types.
1066 ``auto&&`` SHOULD be used to represent mutable reference types.
1067
1068 .. code-block:: c++
1069
1070 std::list<std::string> strings;
1071
1072 for (const auto& str : strings) {
1073 statements; // cannot modify `str`
1074 }
1075 for (auto&& str : strings) {
1076 statements; // can modify `str`
1077 }
Junxiao Shia76bbc92015-03-23 11:05:37 -07001078
10793.30. Annotate with ``override`` or ``final`` when overriding a virtual method or destructor.
1080
1081 ``virtual`` should still be used along with ``override`` and ``final``,
1082 so that a human reader can easily recognize a virtual method
1083 without looking toward the end of the function signature.
1084
1085 .. code-block:: c++
1086
1087 class Stream
1088 {
1089 public:
1090 virtual void
1091 open();
1092 };
1093
1094 class InputStream : public Stream
1095 {
1096 public:
1097 virtual void
1098 open() override;
1099 };
1100
1101 class Console : public InputStream
1102 {
1103 public:
1104 virtual void
1105 open() override;
1106 };
1107
1108 ndn-cxx declares ``NDN_CXX_DECL_OVERRIDE`` and ``NDN_CXX_DECL_FINAL`` macros that
1109 expand to ``override`` and ``final`` if the compiler supports this feature,
1110 but expand to nothing with older compilers.
1111 These must be used in place of ``override`` and ``final``,
1112 so that ndn-cxx remains compatible with older compilers.
1113
1114 ``NDN_CXX_DECL_OVERRIDE`` and ``NDN_CXX_DECL_FINAL`` macros are for ndn-cxx internal use.
1115 Other projects, if adopting this style guide, should define their own macros if needed.
Spyridon Mastorakis0d2ed2e2015-07-27 19:09:12 -07001116
11173.31. The recommended way to throw an exception derived from ``std::exception`` is to use
1118the ``BOOST_THROW_EXCEPTION``
1119`macro <http://www.boost.org/doc/libs/1_42_0/libs/exception/doc/BOOST_THROW_EXCEPTION.html>`__.
1120Exceptions thrown using this macro will be bundled with additional diagnostic information, including
1121filename, line number, and function name from where the exception was thrown.