|
24
|
1 .. _coding-style:
|
|
0
|
2 .. highlight:: c++
|
|
|
3
|
|
|
4 Coding style
|
|
|
5 ============
|
|
|
6
|
|
|
7 .. contents::
|
|
|
8
|
|
|
9 The developers of Orthanc should follow these `C++ Programming Style
|
|
|
10 Guidelines <http://geosoft.no/development/cppstyle.html>`__, that are
|
|
|
11 similar to the so-called "`BSD/Allman style
|
|
|
12 <https://en.wikipedia.org/wiki/Indent_style#Allman_style>`__", with
|
|
|
13 some adaptations that are described below. A compliant Eclipse
|
|
|
14 formatter is `available in the Orthanc distribution
|
|
449
|
15 <https://hg.orthanc-server.com/orthanc/file/default/OrthancFramework/Resources/Graveyard/EclipseCodingStyle.xml>`__ (not maintained anymore).
|
|
0
|
16
|
|
|
17 Licensing
|
|
|
18 ---------
|
|
|
19
|
|
|
20 Do not forget to include licensing information (GPLv3 with OpenSSL
|
|
|
21 exception) in each ``.cpp`` and ``.h``.
|
|
|
22
|
|
|
23 Tabulations
|
|
|
24 -----------
|
|
|
25
|
|
|
26 No tab characters. Replace 1 tab by 2 spaces.
|
|
|
27
|
|
|
28 Strengthened Rules
|
|
|
29 ------------------
|
|
|
30
|
|
|
31 * Rule 31: Use ``COLOR_RED`` instead of ``Color::RED``
|
|
|
32 * Rule 34: Use the suffix ``.cpp``
|
|
|
33 * Rule 35: A single header file must contain a single public class
|
|
|
34 * Rule 72: Use the Example 2 style (aka. Allman style, used by MSDN
|
|
|
35 and Visual Studio)::
|
|
|
36
|
|
|
37 while (!done)
|
|
|
38 {
|
|
|
39 doSomething();
|
|
|
40 done = moreToDo();
|
|
|
41 }
|
|
|
42
|
|
|
43
|
|
|
44 Replaced Rules
|
|
|
45 --------------
|
|
|
46
|
|
|
47 * Rule 6: The names of the methods are camel-case to move the coding style closer to that of the .NET framework.
|
|
|
48 * Rule 36:
|
|
|
49
|
|
|
50 * One-liners are always ok in a ``.h``,
|
|
|
51 * High-performance code is also allowed but only with the inline
|
|
|
52 keyword (the code being moved at the end of the header)
|
|
|
53
|
|
|
54 * Rule 40: Use ``#pragma once`` in each header file (cf. `Wikipedia
|
|
25
|
55 <https://en.wikipedia.org/wiki/Pragma_once>`__)
|
|
0
|
56 * Rules 73 and 80: Use Visual Studio's default style that does not add
|
|
|
57 two whitespaces in front of public, protected, private and case::
|
|
|
58
|
|
|
59 class SomeClass : public BaseClass
|
|
|
60 {
|
|
|
61 public:
|
|
|
62 ...
|
|
|
63 protected:
|
|
|
64 ...
|
|
|
65 private:
|
|
|
66 ...
|
|
|
67 };
|
|
|
68
|
|
|
69
|
|
|
70 Additional Rules
|
|
|
71 ----------------
|
|
|
72
|
|
|
73 * Use C++ exceptions, avoid error codes.
|
|
25
|
74 * Use the `RAII design pattern <https://en.wikipedia.org/wiki/RAII>`__ (Resource Allocation Is Initialization) wherever possible.
|
|
0
|
75 * No C-style casting, use ``static_cast``, ``reinterpret_cast``,
|
|
|
76 ``dynamic_cast`` and ``const_cast``.
|
|
|
77 * Never use ``using namespace`` in header files (except inside inline
|
|
|
78 implementations).
|
|
|
79 * Complement to rule 20: ``Finalize`` is the complementary word to
|
|
|
80 ``Initialize``.
|
|
|
81 * Minimize the number of #include in header files.
|
|
|
82 * Never use ``catch (...)``, except when protecting non-Orthanc code.
|
|
|
83 * To ease unit testing, favor the `JavaBeans
|
|
25
|
84 <https://en.wikipedia.org/wiki/Java_beans>`__ conventions:
|
|
0
|
85
|
|
|
86 * Single constructor without argument,
|
|
|
87 * Use getters/setters.
|
|
25
|
88
|
|
|
89
|
|
|
90 Conventions for pointers and references
|
|
|
91 ---------------------------------------
|
|
|
92
|
|
|
93 Except when clearly stated in the documentation:
|
|
|
94
|
|
|
95 * A function that receives a **reference** to an object as an argument
|
|
|
96 is not responsible for the lifecycle of the object, and must not
|
|
|
97 ``delete`` it. The object is allowed to keep this reference in a
|
|
|
98 member variable. The caller must ensure that the referenced object
|
|
|
99 will not be freed between the object that references it.
|
|
|
100 * A function that receives a **pointer** to an object as an argument
|
|
|
101 takes the ownership of the object.
|
|
|
102 * A function that returns a **reference** to an object indicates that
|
|
|
103 the object should not be freed by the caller.
|
|
|
104 * A function that returns a **pointer** to an object transfers its
|
|
|
105 ownership to the caller. Occasionally, a pointer is also returned to
|
|
|
106 indicate the presence or the absence (represented by ``NULL``) of
|
|
|
107 some resource: In such a case, the pointer must not be freed.
|
