Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/coding-style.rst @ 1005:d9314d6b225b
making sphinx happy
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 20 Dec 2023 08:20:07 +0100 |
parents | 1316bc62b5d5 |
children |
rev | line source |
---|---|
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 | |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
15 <https://orthanc.uclouvain.be/hg/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. |