blob: 63bd327cf88a7dc686cfddb2113a3060af6daac5 [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
Davide Pesavento0b2aa132020-12-11 23:00:02 -05006* "C++ Programming Style Guidelines" by Geotechnical Software Services, Copyright © 1996 – 2011.
7 The original document is available at `<http://geosoft.no/development/cppstyle.html>`_
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07008
Davide Pesavento0b2aa132020-12-11 23:00:02 -05009* NDN Platform "C++, C, C#, Java and JavaScript Code Guidelines".
10 The original document is available at `<https://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/>`_
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070011
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
Davide Pesavento0b2aa132020-12-11 23:00:02 -050034 a = (b + c) * d; // NOT: a=(b+c)*d
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070035
Davide Pesavento0b2aa132020-12-11 23:00:02 -050036 while (true) { // NOT: while(true)
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070037 ...
38
Davide Pesavento0b2aa132020-12-11 23:00:02 -050039 doSomething(a, b, c, d); // NOT: doSomething(a,b,c,d);
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070040
Davide Pesavento0b2aa132020-12-11 23:00:02 -050041 for (i = 0; i < 10; i++) { // NOT: for(i=0;i<10;i++){
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -070042 ...
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 Pesavento0b2aa132020-12-11 23:00:02 -0500246 The ``NDN_CXX_FALLTHROUGH`` annotation must be included whenever there is
Davide Pesavento1c597a12017-10-06 15:34:24 -0400247 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
Junxiao Shicf698182014-11-03 08:37:42 -0700332 [&] (T arg) {
333 statements;
334 }
335
336 [=] (T arg) {
337 statements;
338 }
339
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500340 If the lambda has no parameters, ``()`` should be omitted.
341
342 .. code-block:: c++
343
344 [&capture1, capture2] {
345 statements;
346 }
347
348 Trailing return types should be omitted whenever possible. Add it only when the compiler
349 cannot deduce the return type automatically, or when it improves readability. Note that
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500350 ``()`` is required by the C++ standard when ``mutable`` or a trailing return type is used.
Junxiao Shicf698182014-11-03 08:37:42 -0700351
352 .. code-block:: c++
353
354 [] (T arg) -> int {
355 statements;
356 }
357
358 [] () -> int {
359 statements;
360 }
361
362 If the function body has only one line, and the whole lambda expression can fit in one line,
363 the following form is also acceptable:
364
365 .. code-block:: c++
366
367 [&capture1, capture2] (T1 arg1, T2 arg2) { statement; }
368
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500369 A no-op lambda can be written in a more compact form:
Junxiao Shicf698182014-11-03 08:37:42 -0700370
371 .. code-block:: c++
372
373 []{}
374
Junxiao Shi8b12a5a2014-11-25 10:42:47 -07003751.16. List initialization should have the following form:
376
377 .. code-block:: c++
378
379 T object{arg1, arg2};
380
381 T{arg1, arg2};
382
383 new T{arg1, arg2};
384
385 return {arg1, arg2};
386
387 function({arg1, arg2}, otherArgument);
388
389 object[{arg1, arg2}];
390
391 T({arg1, arg2})
392
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500393 T object = {arg1, arg2};
394
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700395 class Class
396 {
397 private:
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500398 T m_member{arg1, arg2};
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700399 static T s_member = {arg1, arg2};
400 };
401
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700402 An empty braced-init-list is written as ``{}``. For example:
403
404 .. code-block:: c++
405
406 T object{};
Junxiao Shi8b12a5a2014-11-25 10:42:47 -0700407 T object = {};
408
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07004092. Naming Conventions
410---------------------
411
4122.1. C++ header files should have the extension ``.hpp``. Source files should have the
413extension ``.cpp``
414
415 File names should be all lower case. If the class name
416 is a composite of several words, each word in a file name should be separated with a
417 dash (-). A class should be declared in a header file and defined in a source file
418 where the name of the files match the name of the class.
419
420 ::
421
422 my-class.hpp, my-class.cpp
423
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07004242.2. Names representing types must be written in English in mixed case starting with upper case.
425
426 .. code-block:: c++
427
428 class MyClass;
429 class Line;
430 class SavingsAccount;
431
4322.3. Variable names must be written in English in mixed case starting with lower case.
433
434 .. code-block:: c++
435
436 MyClass myClass;
437 Line line;
438 SavingsAccount savingsAccount;
439 int theAnswerToLifeTheUniverseAndEverything;
440
4412.4. Named constants (including enumeration values) must be all uppercase using underscore
442to separate words.
443
444 .. code-block:: c++
445
446 const int MAX_ITERATIONS = 25;
447 const std::string COLOR_RED = "red";
448 static const double PI = 3.14;
449
450 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 -0500451 classes) to implement the value as a method.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700452
453 .. code-block:: c++
454
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500455 static int // declare constexpr if possible
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700456 getMaxIterations()
457 {
458 return 25;
459 }
460
4612.5. Names representing methods or functions must be commands starting with a verb and
462written in mixed case starting with lower case.
463
464 .. code-block:: c++
465
466 std::string
467 getName()
468 {
469 ...
470 }
471
472 double
473 computeTotalWidth()
474 {
475 ...
476 }
477
4782.6. Names representing namespaces should be all lowercase.
479
480 .. code-block:: c++
481
482 namespace model {
483 namespace analyzer {
484
485 ...
486
487 } // namespace analyzer
488 } // namespace model
489
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05004902.7. Names representing generic template types should be a single uppercase letter.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700491
492 .. code-block:: c++
493
494 template<class T> ...
495 template<class C, class D> ...
496
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500497 However, when a template parameter represents a certain concept and is expected
498 to have a certain interface, the name should be explicitly spelled out.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700499
500 .. code-block:: c++
501
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500502 template<class InputIterator> ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700503 template<class Packet> ...
504
5052.8. Abbreviations and acronyms must not be uppercase when used as name.
506
507 .. code-block:: c++
508
509 exportHtmlSource(); // NOT: exportHTMLSource();
510 openDvdPlayer(); // NOT: openDVDPlayer();
511
5122.9. Global variables should have ``g_`` prefix
513
514 .. code-block:: c++
515
516 g_mainWindow.open();
517 g_applicationContext.getName();
518
519 In general, the use of global variables should be avoided. Consider using singleton
520 objects instead.
521
Davide Pesavento0b2aa132020-12-11 23:00:02 -05005222.10. All non-static data members of a class should be prefixed with ``m_`` unless they
523are public. Similarly, non-public static data members should be prefixed with ``s_``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700524
525 .. code-block:: c++
526
527 class SomeClass
528 {
529 private:
530 int m_length;
531
532 static std::string s_name;
533 };
534
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07005352.11. Variables with a large scope should have long (explicit) names, variables with a small
536scope can have short names.
537
538 Scratch variables used for temporary storage or indices are best kept short. A
539 programmer reading such variables should be able to assume that its value is not used
540 outside of a few lines of code. Common scratch variables for integers are ``i``,
541 ``j``, ``k``, ``m``, ``n`` and for characters ``c`` and ``d``.
542
5432.12. The name of the object is implicit, and should be avoided in a method name.
544
545 .. code-block:: c++
546
547 line.getLength(); // NOT: line.getLineLength();
548
549 The latter seems natural in the class declaration, but proves superfluous in use, as
550 shown in the example.
551
5522.13. The terms ``get/set`` must be used where an attribute is accessed directly.
553
554 .. code-block:: c++
555
556 employee.getName();
557 employee.setName(name);
558
559 matrix.getElement(2, 4);
560 matrix.setElement(2, 4, value);
561
5622.14. The term ``compute`` can be used in methods where something is computed.
563
564 .. code-block:: c++
565
566 valueSet.computeAverage();
567 matrix.computeInverse()
568
569 Give the reader the immediate clue that this is a potentially time-consuming operation,
570 and if used repeatedly, he might consider caching the result. Consistent use of the term
571 enhances readability.
572
5732.15. The term ``find`` can be used in methods where something is looked up.
574
575 .. code-block:: c++
576
577 vertex.findNearestVertex();
578 matrix.findMinElement();
579
580 Give the reader the immediate clue that this is a simple look up method with a minimum
581 of computations involved. Consistent use of the term enhances readability.
582
5832.16. Plural form should be used on names representing a collection of objects.
584
585 .. code-block:: c++
586
587 vector<Point> points;
588 int values[];
589
590 Enhances readability since the name gives the user an immediate clue of the type of
591 the variable and the operations that can be performed on its elements.
592
5932.17. The prefix ``n`` should be used for variables representing a number of objects.
594
595 .. code-block:: c++
596
597 nPoints, nLines
598
599 The notation is taken from mathematics where it is an established convention for
600 indicating a number of objects.
601
Eric Newberry436e46f2018-06-10 21:45:57 -07006022.18. The suffix ``Num`` or ``No`` should be used for variables representing an entity number.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700603
604 .. code-block:: c++
605
Eric Newberry436e46f2018-06-10 21:45:57 -0700606 tableNum, tableNo, employeeNum, employeeNo
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700607
6082.19. The prefix ``is``, ``has``, ``need``, or similar should be used for boolean variables and
609methods.
610
611 .. code-block:: c++
612
613 isSet, isVisible, isFinished, isFound, isOpen
614 needToConvert, needToFinish
615
6162.20. Complement names must be used for complement operations, reducing complexity by
617symmetry.
618
619 ::
620
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500621 get/set, add/remove, create/destroy, start/stop, insert/erase,
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700622 increment/decrement, old/new, begin/end, first/last, up/down, min/max,
623 next/previous (and commonly used next/prev), open/close, show/hide,
624 suspend/resume, etc.
625
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500626 The pair ``insert/erase`` is preferred. ``insert/delete`` can also be used if it
627 does not conflict with the ``delete`` keyword of C++.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700628
6292.21. Variable names should not include reference to variable type (do not use Hungarian
630notation).
631
632 .. code-block:: c++
633
634 Line* line; // NOT: Line* pLine;
635 // NOT: Line* linePtr;
636
637 size_t nPoints; // NOT lnPoints
638
639 char* name; // NOT szName
640
6412.22. Negated boolean variable names should be avoided.
642
643 .. code-block:: c++
644
645 bool isError; // NOT: isNoError
646 bool isFound; // NOT: isNotFound
647
6482.23. Enumeration constants recommended to prefix with a common type name.
649
650 .. code-block:: c++
651
652 enum Color {
653 COLOR_RED,
654 COLOR_GREEN,
655 COLOR_BLUE
656 };
657
6582.24. Exceptions can be suffixed with either ``Exception`` (e.g., ``SecurityException``) or
659``Error`` (e.g., ``SecurityError``).
660
Davide Pesavento923ba442019-02-12 22:00:38 -0500661 The recommended method is to declare an exception class ``Exception`` or ``Error`` as
662 a nested type inside the class from which the exception is thrown. For example, when
663 defining a class ``Foo`` that can throw errors, one can write the following:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700664
665 .. code-block:: c++
666
667 #include <stdexcept>
668
669 class Foo
670 {
Junxiao Shi68b53852018-07-25 13:56:38 -0600671 public:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700672 class Error : public std::runtime_error
673 {
674 public:
Junxiao Shi68b53852018-07-25 13:56:38 -0600675 // You can inherit constructors from std::runtime_error like this:
676 using std::runtime_error::runtime_error;
677
Davide Pesavento923ba442019-02-12 22:00:38 -0500678 // Additional constructors, if desired, can be declared as usual:
Junxiao Shi68b53852018-07-25 13:56:38 -0600679 Error(const std::string& what, const std::exception& inner)
680 : std::runtime_error(what + ": " + inner.what())
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700681 {
682 }
683 };
684 };
685
686 In addition to that, if class Foo is a base class or interface for some class
687 hierarchy, then child classes should should define their own ``Error`` or
688 ``Exception`` classes that are inherited from the parent's Error class.
689
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07006902.25. Functions (methods returning something) should be named after what they return and
691procedures (void methods) after what they do.
692
693 Increase readability. Makes it clear what the unit should do and especially all the
694 things it is not supposed to do. This again makes it easier to keep the code clean of
695 side effects.
696
6973. Miscellaneous
698----------------
699
7003.1. Exceptions can be used in the code, but should be used only in exceptional cases and
701not in the primary processing path.
702
7033.2. Header files must contain an include guard.
704
Davide Pesavento7e780642018-11-24 15:51:34 -0500705 For example, a header file named ``module/class-name.hpp`` or
706 ``src/module/class-name.hpp`` should have a header guard in the following form:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700707
708 .. code-block:: c++
709
710 #ifndef APP_MODULE_CLASS_NAME_HPP
711 #define APP_MODULE_CLASS_NAME_HPP
712 ...
713 #endif // APP_MODULE_CLASS_NAME_HPP
714
Davide Pesavento7e780642018-11-24 15:51:34 -0500715 The macro name should reflect the path of the header file relative to the root of the
716 source tree, in order to prevent naming conflicts. The header guard should be prefixed
717 with the application/library name to avoid conflicts with other packages and libraries.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700718
Davide Pesavento7e780642018-11-24 15:51:34 -05007193.3. Include directives for system headers and other external libraries should use
720``<angle brackets>``. Header files in the same source code repository should be included
721using ``"quotes"``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700722
723 .. code-block:: c++
724
Davide Pesavento7e780642018-11-24 15:51:34 -0500725 #include "ndn-cxx/util/random.hpp"
726
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700727 #include <string>
728 #include <boost/lexical_cast.hpp>
729
Davide Pesavento7e780642018-11-24 15:51:34 -0500730 All of a project's header files should be included with their path relative to
731 the project's source directory. The use of UNIX directory shortcuts ``.``
732 (the current directory) and ``..`` (the parent directory) is discouraged.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700733
Junxiao Shi4f92d872017-07-25 22:04:48 +00007343.4. Include statements should be grouped. Same-project headers should be included first.
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500735Leave an empty line between groups of include statements. Sort alphabetically within a group.
Davide Pesavento7e780642018-11-24 15:51:34 -0500736For example, the include section of ``ndn-cxx/foo/bar.cpp`` may look like this:
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700737
738 .. code-block:: c++
739
Junxiao Shi24c5a002018-12-12 04:47:15 +0000740 #include "ndn-cxx/impl/pending-interest.hpp"
Davide Pesavento7e780642018-11-24 15:51:34 -0500741 #include "ndn-cxx/util/random.hpp"
Junxiao Shi4f92d872017-07-25 22:04:48 +0000742
Davide Pesavento7e780642018-11-24 15:51:34 -0500743 #include <cstdlib>
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700744 #include <fstream>
745 #include <iomanip>
746
747 #include <boost/lexical_cast.hpp>
748 #include <boost/regex.hpp>
749
Davide Pesavento0b2aa132020-12-11 23:00:02 -05007503.5. Definitions that are local to only one ``.cpp`` file should be declared inside that
751file and be placed in an unnamed namespace or declared ``static``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700752
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07007533.6. Implicit conversion is generally allowed.
754
755 Implicit conversion between integer and floating point numbers can cause problems and
756 should be avoided.
757
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500758 Implicit conversion in constructors that can be called with a single argument is usually
759 undesirable. Therefore, all single-argument constructors should be marked ``explicit``,
760 unless implicit conversion is desirable. In that case, a comment should document the
761 reason for this.
762 As an exception, copy and move constructors should not be explicit, since they do not
763 perform type conversion.
764 Constructors that cannot be called with a single argument may omit ``explicit``.
765 Constructors that take a single ``std::initializer_list`` parameter should also omit
766 ``explicit``, in order to support copy-initialization.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700767
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500768 Avoid C-style casts.
769 Use ``static_cast``, ``dynamic_cast``, ``const_cast``, ``reinterpret_cast``, or
770 ``bit_cast`` instead where appropriate.
771 Use ``static_pointer_cast``, ``dynamic_pointer_cast``, or ``const_pointer_cast``
772 when dealing with ``shared_ptr``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700773
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07007743.7. Variables should be initialized where they are declared.
775
776 This ensures that variables are valid at any time. Sometimes it is impossible to
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500777 initialize a variable to a valid value where it is declared.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700778
779 .. code-block:: c++
780
781 int x, y, z;
782 getCenter(&x, &y, &z);
783
784 In these cases it should be left uninitialized rather than initialized to some phony
785 value.
786
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05007873.8. In most cases, class data members should not be declared ``public``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700788
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500789 Public data members violate the concepts of information hiding and encapsulation.
790 Use private variables and public accessor methods instead.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700791
792 Exceptions to this rule:
793
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500794 * When the class is essentially a passive data structure with no or minimal behavior
795 (equivalent to a C struct, also known as POD type). In this case, all fields should
796 be public and the keyword ``struct`` should be used instead of ``class``.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700797
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500798 * When the class is used only inside the compilation unit, e.g., when implementing pImpl
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700799 idiom (aka Bridge pattern) or similar cases.
800
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -07008013.9. C++ pointers and references should have their reference symbol next to the type rather
802than to the name.
803
804 .. code-block:: c++
805
806 float* x; // NOT: float *x;
807 int& y; // NOT: int &y;
808
8093.10. Implicit test for 0 should not be used other than for boolean variables and pointers.
810
811 .. code-block:: c++
812
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500813 if (nLines != 0) // NOT: if (nLines)
814
815 int* ptr = ...
816 if (ptr) // OK
817 if (ptr != nullptr) // also OK
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700818
Davide Pesaventobbca1b92015-12-25 20:06:00 +01008193.11. *(removed)*
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700820
8213.12. Loop variables should be initialized immediately before the loop.
822
823 .. code-block:: c++
824
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500825 bool isDone = false; // NOT: bool isDone = false;
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700826 while (!isDone) { // // other stuff
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500827 ... // while (!isDone) {
828 } // ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700829 // }
830
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05008313.13. The form ``while (true)`` should be used for infinite loops.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700832
833 .. code-block:: c++
834
835 while (true) {
836 ...
837 }
838
839 // NOT:
840 for (;;) { // NO!
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500841 ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700842 }
843 while (1) { // NO!
Davide Pesavento0b2aa132020-12-11 23:00:02 -0500844 ...
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700845 }
846
8473.14. Complex conditional expressions must be avoided. Introduce temporary boolean variables
848instead.
849
850 .. code-block:: c++
851
852 bool isFinished = (elementNo < 0) || (elementNo > maxElement);
853 bool isRepeatedEntry = elementNo == lastElement;
854 if (isFinished || isRepeatedEntry) {
855 ...
856 }
857
858 // NOT:
859 // if ((elementNo < 0) || (elementNo > maxElement) || elementNo == lastElement) {
860 // ...
861 // }
862
863 By assigning boolean variables to expressions, the program gets automatic
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500864 documentation. The construction will be easier to read, debug, and maintain.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700865
8663.15. The conditional should be put on a separate line.
867
868 .. code-block:: c++
869
870 if (isDone) // NOT: if (isDone) doCleanup();
871 doCleanup();
872
873 This is for debugging purposes. When writing on a single line, it is not apparent
874 whether the test is really true or not.
875
8763.16. Assignment statements in conditionals must be avoided.
877
878 .. code-block:: c++
879
880 File* fileHandle = open(fileName, "w");
881 if (!fileHandle) {
882 ...
883 }
884
885 // NOT
886 // if (!(fileHandle = open(fileName, "w"))) {
887 // ..
888 // }
889
8903.17. The use of magic numbers in the code should be avoided. Numbers other than 0 and 1
891should be considered declared as named constants instead.
892
893 If the number does not have an obvious meaning by itself, the readability is enhanced
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500894 by introducing a named constant instead. A different approach is to introduce a method
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700895 from which the constant can be accessed.
896
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -05008973.18. Floating point literals should always be written with a decimal point, at least one
898decimal, and without omitting 0 before the decimal point.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700899
900 .. code-block:: c++
901
902 double total = 0.0; // NOT: double total = 0;
903 double someValue = 0.1; // NOT double someValue = .1;
904 double speed = 3.0e8; // NOT: double speed = 3e8;
905 double sum;
906 ...
907 sum = (a + b) * 10.0;
908
9093.19. ``goto`` should not be used.
910
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500911 ``goto`` statements violate the idea of structured code. Only in very few cases (for
912 instance, breaking out of deeply nested structures) should ``goto`` be considered,
913 and only if the alternative structured counterpart is proven to be less readable.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700914
Junxiao Shi03b15b32014-10-30 21:10:25 -07009153.20. ``nullptr`` should be used to represent a null pointer, instead of "0" or "NULL".
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700916
9173.21. Logical units within a block should be separated by one blank line.
918
919 .. code-block:: c++
920
921 Matrix4x4 matrix = new Matrix4x4();
922
923 double cosAngle = Math.cos(angle);
924 double sinAngle = Math.sin(angle);
925
926 matrix.setElement(1, 1, cosAngle);
927 matrix.setElement(1, 2, sinAngle);
928 matrix.setElement(2, 1, -sinAngle);
929 matrix.setElement(2, 2, cosAngle);
930
931 multiply(matrix);
932
933 Enhance readability by introducing white space between logical units of a block.
934
9353.22. Variables in declarations can be left aligned.
936
937 .. code-block:: c++
938
939 AsciiFile* file;
940 int nPoints;
941 float x, y;
942
943 Enhance readability. The variables are easier to spot from the types by alignment.
944
9453.23. Use alignment wherever it enhances readability.
946
947 .. code-block:: c++
948
949 value = (potential * oilDensity) / constant1 +
950 (depth * waterDensity) / constant2 +
951 (zCoordinateValue * gasDensity) / constant3;
952
953 minPosition = computeDistance(min, x, y, z);
954 averagePosition = computeDistance(average, x, y, z);
955
956 There are a number of places in the code where white space can be included to enhance
957 readability even if this violates common guidelines. Many of these cases have to do
958 with code alignment. General guidelines on code alignment are difficult to give, but
959 the examples above should give a general clue.
960
9613.24. All comments should be written in English.
962
Davide Pesaventoaf1d6cf2017-11-06 23:53:01 -0500963 In an international environment, English is the preferred language.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700964
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07009653.25. Use ``//`` for all comments, including multi-line comments.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700966
967 .. code-block:: c++
968
969 // Comment spanning
970 // more than one line.
971
972 Since multilevel C-commenting is not supported, using ``//`` comments ensure that it
973 is always possible to comment out entire sections of a file using ``/* */`` for
974 debugging purposes etc.
975
976 There should be a space between the ``//`` and the actual comment, and comments should
977 always start with an upper case letter and end with a period.
978
979 However, method and class documentation comments should use ``/** */`` style for
Junxiao Shibd2cedb2017-07-05 18:51:52 +0000980 Doxygen, JavaDoc and JSDoc. License boilerplate should use ``/* */`` style.
Alexander Afanasyev3aeeaeb2014-04-22 23:34:23 -0700981
9823.26. Comments should be included relative to their position in the code.
983
984 .. code-block:: c++
985
986 while (true) {
987 // Do something
988 something();
989 }
990
991 // NOT:
992 while (true) {
993 // Do something
994 something();
995 }
996
997 This is to avoid that the comments break the logical structure of the program.
Junxiao Shiae61aac2014-11-04 14:57:38 -0700998
9993.27. Use ``BOOST_ASSERT`` and ``BOOST_ASSERT_MSG`` for runtime assertions.
1000
1001 .. code-block:: c++
1002
1003 int x = 1;
1004 int y = 2;
1005 int z = x + y;
1006 BOOST_ASSERT(z - y == x);
1007
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001008 The expression passed to ``BOOST_ASSERT`` must not have side effects,
1009 because it may not be evaluated in release builds.
Junxiao Shiae61aac2014-11-04 14:57:38 -07001010
Davide Pesavento0b2aa132020-12-11 23:00:02 -050010113.28. Use ``static_assert`` for compile-time assertions.
Junxiao Shiae61aac2014-11-04 14:57:38 -07001012
Junxiao Shiae61aac2014-11-04 14:57:38 -07001013 .. code-block:: c++
1014
1015 class BaseClass
1016 {
1017 };
1018
1019 class DerivedClass : public BaseClass
1020 {
1021 };
1022
1023 static_assert(std::is_base_of<BaseClass, DerivedClass>::value,
1024 "DerivedClass must inherit from BaseClass");
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001025
Davide Pesavento0b2aa132020-12-11 23:00:02 -050010263.29. The ``auto`` type specifier may be used for local variables if a human reader can
1027easily deduce the actual type, or if it makes the code safer.
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001028
1029 .. code-block:: c++
1030
1031 std::vector<int> intVector;
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001032 auto i = intVector.find(4); // OK
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001033
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001034 auto stringSet = std::make_shared<std::set<std::string>>(); // OK
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001035
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001036 std::vector<std::string> strings;
1037 for (const auto& str : strings) { // OK, iterating over the elements of a container
1038 std::cout << str;
Junxiao Shic0a8c3b2014-11-08 12:09:05 -07001039 }
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001040
1041 obj.onEvent([] (auto&&...) { std::cout << "hi!"; }); // OK, unused lambda parameters
1042
1043 auto x = foo(); // BAD unless foo() is declared nearby or has a well-known prototype
Junxiao Shia76bbc92015-03-23 11:05:37 -07001044
Davide Pesaventode2a1c22016-12-11 15:46:13 -050010453.30. Use the ``override`` or ``final`` specifier when overriding a virtual
1046member function or a virtual destructor.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001047
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001048 ``virtual`` must not be used along with ``final`` so that the compiler can generate
1049 an error when a final function does not override.
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001050
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001051 ``virtual`` should not be used along with ``override`` for consistency with ``final``.
Junxiao Shia76bbc92015-03-23 11:05:37 -07001052
1053 .. code-block:: c++
1054
1055 class Stream
1056 {
1057 public:
1058 virtual void
1059 open();
1060 };
1061
1062 class InputStream : public Stream
1063 {
1064 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001065 void
Junxiao Shia76bbc92015-03-23 11:05:37 -07001066 open() override;
1067 };
1068
1069 class Console : public InputStream
1070 {
1071 public:
Davide Pesaventode2a1c22016-12-11 15:46:13 -05001072 void
1073 open() final;
Junxiao Shia76bbc92015-03-23 11:05:37 -07001074 };
1075
Spyridon Mastorakis0d2ed2e2015-07-27 19:09:12 -070010763.31. The recommended way to throw an exception derived from ``std::exception`` is to use
Davide Pesavento923ba442019-02-12 22:00:38 -05001077``NDN_THROW`` or one of the other ``NDN_THROW_*`` macros.
Davide Pesavento0b2aa132020-12-11 23:00:02 -05001078
1079 Exceptions thrown using these macros will be augmented with additional diagnostic
1080 information, including the file name, line number, and function name from which
1081 the exception was thrown.
1082
1083 The extended diagnostic information contained in the exception can be printed with
1084 ``boost::diagnostic_information()``.
1085
1086 .. code-block:: c++
1087
1088 #include <boost/exception/diagnostic_information.hpp>
1089 #include <iostream>
1090
1091 try {
1092 operationThatMayThrow();
1093 }
1094 catch (const std::exception& e) {
1095 std::cerr << boost::diagnostic_information(e);
1096 }