STYLE.md

Thu, 18 Oct 2018 21:21:00 +0200

author
David Demelier <markand@malikania.fr>
date
Thu, 18 Oct 2018 21:21:00 +0200
changeset 39
ddf3183ec5ce
parent 37
a77a41f83ebb
child 40
cb25a20c1fc9
permissions
-rw-r--r--

Add indent paragraph

17
314e8bb2659a Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents: 16
diff changeset
1 PROJECT NAME CODING STYLE
314e8bb2659a Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents: 16
diff changeset
2 =========================
314e8bb2659a Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents: 16
diff changeset
3
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
4 File content
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
5 ============
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
6
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
7 - Use UTF-8 charset,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
8 - Use Unix line endings,
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
9 - Never write two blank consecutives blank lines.
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
10
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
11 Indent
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
12 ======
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
13
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
15 indenting code and have the advantage of being configurable. On the other hand
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
16 to keep code clean, you must align content with spaces only *within* a line.
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
17
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
18 Note: we recommend 8 columns to avoid high number of indentations.
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
19
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
20 Example (show whitespace in your editor)
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
21
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
22 ```cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
23 class foo {
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
24 public:
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
25 enum type {
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
26 dummy_value, // dummy comment
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
27 other_value // other comment
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
28 };
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
29
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
30 void long_function_name(very_long_type x1,
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
31 very_long_type x2)
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
32 {
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
33 const map<string, string> m{
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
34 { "hostname", "127.0.0.1" },
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
35 { "port", "6667" }
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
36 };
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
37 }
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
38 };
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
39 ```
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
40
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
41 As a rule of thumb, tabs must always be all length.
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
42
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
43 Example of incorrect usage:
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
44
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
45 ```cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
46 { "hostname", "127.0.0.1" },
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
47 { "port", "6667" }
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
48 ```
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
49
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
50 This example will not align correctly if tabstops are not set to 8.
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
51
17
314e8bb2659a Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents: 16
diff changeset
52 C++
314e8bb2659a Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents: 16
diff changeset
53 ===
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
54
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 Style
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 -----
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
57
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
58 - Do not exceed 120 columns for lines of code,
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
59 - Do not exceed 80 columns for comments,
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
60
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 ### Braces
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 Braces follow the K&R style, they are never placed on their own lines except for
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 function definitions.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
65
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
66 Do not put braces for single line statements.
10
eaae1fcabca8 Update braces style
David Demelier <markand@malikania.fr>
parents: 9
diff changeset
67
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
68 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
69 if (condition) {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
70 apply();
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
71 add();
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
72 } else
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
73 ok();
10
eaae1fcabca8 Update braces style
David Demelier <markand@malikania.fr>
parents: 9
diff changeset
74
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
75 if (condition)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
76 validate();
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
77
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
78 if (foo)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
79 state = long + conditional + that + requires + several + lines +
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
80 to + complete;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
81 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
82
10
eaae1fcabca8 Update braces style
David Demelier <markand@malikania.fr>
parents: 9
diff changeset
83 Functions require braces on their own lines.
eaae1fcabca8 Update braces style
David Demelier <markand@malikania.fr>
parents: 9
diff changeset
84
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
85 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
86 void function()
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
87 {
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
88 }
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
89 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
90
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 And a lambda has its braces on the same lines too:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
93 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
94 sort([&] (auto&) {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
95 return true;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
96 });
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
97 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
98
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 ### Spaces
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
100
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 its argument.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
103
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 Normal function calls do not require it.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
105
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
106 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
107 if (foo)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
108 destroy(sizeof (int));
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
109 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
110
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 ### References and pointers
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
112
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 References and pointers are always next to the type name and not the variable.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
114
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
115 ```cpp
34
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
116 auto get(const std::string& name) -> T&;
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
117
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
118 int* p = &x;
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
119 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
120
34
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
121 ### Trailing return syntax
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
122
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
123 We use trailing return syntax everywhere, it has the following benefits:
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
124
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
125 - Inner types don't need to be prefixed by class name,
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
126 - Functions are kept aligned correctly, focusing on the function name.
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
127
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
128 ```cpp
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
129 auto func() -> std::string;
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
130 ```
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
131
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 ### Naming
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
133
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
134 - English names,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
135 - Member variables have trailing underscore (e.g foo\_bar\_),
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
136 - No hungarian notation.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
137
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 Everything is in `underscore_case` except template parameters and macros.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
139
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
140 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
141 #if defined(FOO)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
142 # include <foo.hpp>
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
143 #endif
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
144
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
145 namespace baz {
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
146
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
147 class object {
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
148 private:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
149 std::string name_;
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
150
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
151 public:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
152 auto name() const noexcept -> const std::string&;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
153 };
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
154
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
155 template <typename Archive>
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
156 void open(const Archive& ar)
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
157 {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
158 bool is_valid = false;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
159 }
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
160
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
161 } // !baz
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
162 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
163
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 ### Header guards
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
165
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
166 Do not use `#pragma once`.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
167
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
168 Header guards are usually named `PROJECT_COMPONENT_FILENAME_HPP`.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
169
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
170 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
171 #ifndef FOO_COMMON_UTIL_HPP
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
172 #define FOO_COMMON_UTIL_HPP
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
173
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
174 #endif // !FOO_COMMON_UTIL_HPP
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
175 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
176
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
177 ### Enums
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
178
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
179 Enumerations constants are always defined in separate line to allow commenting
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
180 them as doxygen.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
181
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
182 Enum class are encouraged.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
183
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
184 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
185 enum class color {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
186 blue,
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
187 red,
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
188 green
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
189 };
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
190 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
191
16
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
192 ### Switch
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
193
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
194 In a switch case statement, you **must** not declare variables and not indent
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
195 cases.
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
196
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
197 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
198 switch (variable) {
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
199 case foo:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
200 do_some_stuff();
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
201 break;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
202 default:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
203 break;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
204 }
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
205 ```
16
780c138ab41d Add a note about switch
David Demelier <markand@malikania.fr>
parents: 14
diff changeset
206
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
207 ### Files
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
208
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
209 - Use `.cpp` and `.hpp` as file extensions,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
210 - Filenames are all lowercase.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
211
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
212 ### Comments
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
213
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
214 Avoid useless comments in source files. Comment complex things or why it is done
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
215 like this. However any public function in the .hpp **must** be documented as
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
216 doxygen without exception.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
217
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
218 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
219 /*
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
220 * Multi line comments look like
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
221 * this.
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
222 */
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
223
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
224 // Short comment
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
225 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
226
2
1e34b51d9c52 Add note about if 0
David Demelier <markand@malikania.fr>
parents: 1
diff changeset
227 Use `#if 0` to comment blocks of code.
1e34b51d9c52 Add note about if 0
David Demelier <markand@malikania.fr>
parents: 1
diff changeset
228
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
229 ```cpp
2
1e34b51d9c52 Add note about if 0
David Demelier <markand@malikania.fr>
parents: 1
diff changeset
230 #if 0
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
231 broken_stuff();
2
1e34b51d9c52 Add note about if 0
David Demelier <markand@malikania.fr>
parents: 1
diff changeset
232 #endif
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
233 ```
2
1e34b51d9c52 Add note about if 0
David Demelier <markand@malikania.fr>
parents: 1
diff changeset
234
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
235 ### Includes
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
236
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
237 The includes should always come in the following order.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
238
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
239 1. C++ headers
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
240 2. C header
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
241 3. Third party libraries
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
242 4. Application headers in ""
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
243
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
244 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
245 #include <cstring>
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
246 #include <cerrno>
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
247
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
248 #include <sys/stat.h>
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
249
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
250 #include <libircclient.h>
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
251
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
252 #include "foo.h"
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
253 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
254
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
255 Note: always use C++ headers for C equivalent, stdio.h -> cstdio, etc.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
256
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
257 Programming
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
258 -----------
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
259
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
260 ### C language
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
261
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
262 Do not use old C stuff like `void*`, `srand/rand`, `printf` or anything that
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
263 can be rewritten in modern C++.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
264
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
265 ### RTTI
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
266
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
267 Usage of `dynamic_cast` and `typeid` are completely disallowed in any shape of
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
268 form.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
269
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
270 ### Arguments
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
271
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
272 It is recommended to pass parameters by value or const reference. Usage of
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
273 non-const reference as output parameter is **discouraged** and should be avoided
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
274 in many case because it does not allow chaining of expressions like:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
275
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
276 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
277 std::cout << reverse(upper(clean(" hello world! "))) << std::endl;
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
278 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
279
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
280 If your function is designed to return a modified value passed as argument, it
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
281 is better to take it by value and modify it directly.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
282
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
283 ```cpp
34
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
284 auto clean(std::string input) -> std::string
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
285 {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
286 if (!input.empty() && input.back() == '\r')
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
287 input.pop_back();
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
288
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
289 return input;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
290 }
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
291 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
292
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
293 Never pass primitive types as const value.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
294
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
295 ### Assertions
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
296
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
297 Use the `assert` macro from the cassert header file to verify programming
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
298 errors.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
299
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
300 For example, you may use `assert` to verify that the developer access the data
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
301 between the bounds of an array:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
302
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
303 ```cpp
34
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
304 auto operator[](unsigned index) -> T&
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
305 {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
306 assert(index < length_);
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
307
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
308 return data_[index];
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
309 }
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
310 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
311
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
312 The `assert` macro is not meant to check that a function succeeded, this code
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
313 must not be written that way:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
314
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
315 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
316 assert(listen(10));
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
317 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
318
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
319 ### Exceptions
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
320
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
321 You must use exceptions to indicate an error that was unexpected such as:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
322
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
323 - Failing to open a file,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
324 - I/O unexpected errors,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
325 - Parsing errors,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
326 - User errors.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
327
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
328 You may use the C++ standard exceptions defined in the stdexcept header but if
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
329 you need to carry more data within your exception, you should derive from
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
330 `std::exception`.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
331
14
55bb3689093f Add chapter about error codes
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
332 ### Error code
55bb3689093f Add chapter about error codes
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
333
55bb3689093f Add chapter about error codes
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
334 You should not use error codes to indicate errors, instead use exceptions.
55bb3689093f Add chapter about error codes
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
335 Error codes are allowed in Boost.Asio though.
55bb3689093f Add chapter about error codes
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
336
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
337 ### Free functions
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
338
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
339 Basic utility functions should be defined in a namespace as a free function not
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
340 as a static member function, we're doing C++ not Java.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
341
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
342 Example:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
343
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
344 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
345 namespace util {
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
346
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
347 auto clean(std::string input) -> std::string;
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
348
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
349 } // !util
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
350 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
351
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
352 ### Variables initialization
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
353
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
354 Use parentheses to initialize non primitive types:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
355
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
356 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
357 throw std::runtime_error("foo");
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
358
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
359 my_class obj("bar");
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
360 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
361
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
362 Use brace initialization when you want to use an initializer list, type
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
363 elision:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
364
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
365 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
366 std::vector<int> v{1, 2, 3};
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
367
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
368 foo({1, 2}); // type deduced
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
369
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
370 return { "true", false }; // std::pair returned
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
371 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
372
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
373 Use the assignment for primitive types:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
374
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
375 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
376 int x = 123;
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
377 bool is_valid = true;
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
378 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
379
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
380 ### Classes
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
381
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
382 Classes are usually defined in the following order:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
383
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
384 1. Public inner types (enums, classes),
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
385 2. Protected/private members and functions
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
386 3. Public static functions.
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
387 3. Public member functions
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
388 4. Public virtual functions.
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
389
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
390 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
391 class foo {
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
392 public:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
393 enum class type {
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
394 a,
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
395 b
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
396 };
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
397
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
398 private:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
399 int member_{0};
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
400
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
401 public:
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
402 void some_function();
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
403 };
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
404 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
405
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
406 ### Structs
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
407
31
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
408 Use structs for objects that only need to store public data and have no
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
409 invariants. For example PODs and traits match this criteria:
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
410
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
411 ```cpp
31
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
412 struct point {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
413 int x{0};
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
414 int y{0};
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
415 };
31
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
416
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
417 template <>
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
418 struct info_traits<point> {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
419 template <typename Archive>
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
420 static void serialize(Archive& ar, const point& point)
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
421 {
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
422 ar.write(point.x);
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
423 ar.write(point.y);
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
424 }
31
5ea2876ac37a Relax usage of structs
David Demelier <markand@malikania.fr>
parents: 28
diff changeset
425 };
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
426 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
427
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
428 ### Return
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
429
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
430 The preferred style is to return early in case of errors. That makes the code
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
431 more linear and not highly indented.
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
432
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
433 This code is preferred:
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
434
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
435 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
436 if (a_condition_is_not_valid)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
437 return nullptr;
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
438 if (an_other_condition)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
439 return nullptr;
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
440
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
441 auto x = std::make_shared<object>();
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
442
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
443 x->start();
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
444 x->save();
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
445
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
446 return x;
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
447 ```
0
a8462a503697 Initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
448
1
9bf9b4634339 Update return statement
David Demelier <markand@malikania.fr>
parents: 0
diff changeset
449 Additional rules:
9bf9b4634339 Update return statement
David Demelier <markand@malikania.fr>
parents: 0
diff changeset
450
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
451 - Do never put parentheses between the returned value,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
452 - Do not put a else branch after a return.
13
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
453
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
454 ### Auto
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
455
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
456 We encorage usage of `auto`, it reduces code maintainance as you don't need to
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
457 change your code when your rename types.
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
458
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
459 ```cpp
13
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
460 auto it = std::find_if(v.begin(), v.end(), [&] (const auto& obj) {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
461 return obj.key() == "foo";
13
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
462 });
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
463
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
464 for (const auto& pair : a_map)
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
465 std::cout << pair.first << " = " << pair.second << std::endl;
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
466 ```
13
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
467
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
468 But do not use `auto` to write code like in python, this is not acceptable:
4d6bf8b3446d Add chapter about auto
David Demelier <markand@malikania.fr>
parents: 12
diff changeset
469
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
470 ```cpp
34
3bf129646979 Add TRS paragraph
David Demelier <markand@malikania.fr>
parents: 33
diff changeset
471 auto o = my_object("foo");
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
472 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
473
32
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
474 ### String views
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
475
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
476 Use `std::string_view` each time you need a string that you will not own, this
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
477 includes: temporary arguments, return values, compile time constants.
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
478
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
479 ```cpp
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
480 const std::string_view version("1.0");
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
481
33
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
482 void load(std::string_view id, std::string_view path)
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
483 {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
484 std::cout << "loading: " << id << " from path: " << path << std::endl;
33
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
485 }
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
486 ```
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
487
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
488 ### Optional values
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
489
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
490 Use `std::optional` to indicate a null value considered as valid. For example,
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
491 searching a value that may not exist.
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
492
793a60620477 Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents: 32
diff changeset
493 ```cpp
32
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
494 auto find(std::string_view id) -> std::optional<int>
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
495 {
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
496 if (auto it = foo.find(id); it != foo.end())
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
497 return it->second;
32
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
498
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
499 return std::nullopt;
32
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
500 }
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
501 ```
651aee870e36 Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents: 31
diff changeset
502
35
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
503 ### Avoid definitions in headers
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
504
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
505 Try to avoid as much as possible function definition in header file. It slow
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
506 down compilation because the compiler has to parse the syntax over and over.
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
507 It's even worse as you may need to recompile a lot of files when you change a
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
508 header rather than a source file.
6114710feda7 Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents: 34
diff changeset
509
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
510 CMake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
511 =====
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
512
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
513 Style
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
514 -----
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
515
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
516 - Try to keep line shorter than 80 columns
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
517
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
518 ### Spaces
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
519
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
520 Each programming keyword (e.g. `if`, `foreach`, `while`) requires a single space
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
521 before its argument, otherwise write opening parenthese directly after.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
522
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
523 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
524 foreach (c ${COMPONENTS})
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
525 string(TOUPPER ${c} CMP)
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
526
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
527 if (${WITH_${CMP}})
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
528 add_executable(${c} ${c}.cpp)
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
529 endif ()
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
530 endforeach ()
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
531 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
532
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
533 ### Line breaks
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
534
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
535 When CMake lines goes too long, you should indent arguments at the same level,
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
536 it's also common to see named argument values indented even more.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
537
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
538 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
539 set(
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
540 FILES
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
541 ${myapp_SOURCE_DIR}/main.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
542 ${myapp_SOURCE_DIR}/foo.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
543 ${myapp_SOURCE_DIR}/bar.cpp
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
544 )
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
545
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
546 command_with_lot_of_arguments(
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
547 TARGET foo
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
548 INSTALL On
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
549 SOURCES
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
550 ${myapp_SOURCE_DIR}/main.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
551 ${myapp_SOURCE_DIR}/foo.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
552 ${myapp_SOURCE_DIR}/bar.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
553 COMMENT "Some comment"
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
554 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
555
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
556 Modern CMake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
557 ------------
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
558
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
559 CMake evolves over time, if you have read very old articles there is a chance
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
560 that what you have read is actually deprecated and replaced by other features.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
561 The following list is a short summary of modern CMake features that you must
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
562 use.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
563
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
564 ### Imported targets
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
565
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
566 When they are available, use imported targets rather than plain variables. They
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
567 offer complete dependency tracking with options and include directories as well.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
568
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
569 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
570 find_package(Boost COMPONENTS system)
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
571 target_link_libraries(main Boost::system)
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
572 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
573
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
574 ### Use generator expressions
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
575
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
576 Use generator expressions as much as you can, they offer much more flexibility
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
577 in case of multiple generators. Remember that CMake is not meant to be used only
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
578 with Makefiles.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
579
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
580 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
581 target_link_libraries(
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
582 myapp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
583 $<$<STREQUAL:${CMAKE_SYSTEM_NAME},Windows>:shlwapi>
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
584 $<$<STREQUAL:${CMAKE_SYSTEM_NAME},Linux>:dl>
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
585 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
586
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
587 Warning: do never test against `CMAKE_BUILD_TYPE` in any CMakeLists.txt, IDEs
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
588 like Visual Studio will mismatch what you'll put in the conditions.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
589
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
590 ### Avoid global scoping
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
591
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
592 The following commands must be avoided as much as possible:
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
593
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
594 - `link_directories`,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
595 - `link_libraries`,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
596 - `include_directories`,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
597 - `add_definitions`.
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
598
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
599 They pollute the global namespace, all targets defined after these commands will
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
600 be built against those settings. Instead, you should use the per-targets
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
601 commands.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
602
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
603 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
604 target_include_directories(
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
605 mylib
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
606 PUBLIC
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
607 $<BUILD_INTERFACE:${mylib_SOURCE_DIR}>
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
608 $<INSTALL_INTERFACE:include>
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
609 )
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
610 target_link_libraries(mylib foo)
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
611 ```
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
612
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
613 ### Defining sources
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
614
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
615 You MUST never use any kind of `file(GLOB)` commands to list sources for an
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
616 executable. CMake is designed to be re-called by itself only when required,
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
617 having such a construct will not let CMake be able to detect if you have
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
618 added/removed files in your source directory. Instead, you MUST always specify
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
619 all source by hands.
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
620
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
621 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
622 set(
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
623 FILES
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
624 ${myapp_SOURCE_DIR}/main.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
625 ${myapp_SOURCE_DIR}/a.cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
626 ${myapp_SOURCE_DIR}/b.cpp
25
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
627 )
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
628
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
629 add_executable(myapp ${FILES})
9573e6c9ac97 Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents: 17
diff changeset
630 ```
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
631
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
632 Markdown
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
633 ========
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
634
37
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
635 Headers
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
636 -------
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
637
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
638 For 1st and 2nd level headers, use `===` and `---` delimiters and underline the
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
639 whole title. Otherwise use `###`.
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
640
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
641 ```markdown
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
642 Top level title
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
643 ===============
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
644
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
645 Sub title
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
646 ---------
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
647
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
648 ### Header 3
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
649
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
650 #### Header 4
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
651
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
652 ##### Header 5
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
653
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
654 ###### Header 6
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
655 ```
a77a41f83ebb Add header style to markdown
David Demelier <markand@malikania.fr>
parents: 35
diff changeset
656
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
657 Lists
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
658 -----
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
659
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
660 Use hyphens for unordered lists for consistency, do not indent top level lists,
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
661 then indent by two spaces each level
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
662
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
663 ```markdown
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
664 - unordered list 1
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
665 - unordered list 2
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
666 - sub unordered item
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
667
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
668 1. unordered list 1
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
669 2. unordered list 2
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
670 2.1. sub unordered item
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
671 ```
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
672
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
673 Code blocks
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
674 -----------
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
675
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
676 You can use three backticks and the language specifier or just indent a block by
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
677 for leading spaces if you don't need syntax.
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
678
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
679 ```cpp
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
680 std::cout << "hello world" << std::endl;
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
681 ```
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
682
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
683 And without syntax:
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
684
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
685 ```markdown
39
ddf3183ec5ce Add indent paragraph
David Demelier <markand@malikania.fr>
parents: 37
diff changeset
686 This is simple code block.
27
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
687 ```
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
688
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
689 Tables
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
690 ------
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
691
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
692 Tables are supported and formatted as following:
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
693
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
694 ```markdown
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
695 | header 1 | header 2 |
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
696 |----------|----------|
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
697 | item 1 | item 2 |
0706d01e073f Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents: 25
diff changeset
698 ```
28
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
699
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
700 Alerts
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
701 ------
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
702
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
703 It's possible to prefix a paragraph by one of the following topic, it renders a
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
704 different block depending on the output format:
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
705
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
706 - Note:
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
707 - Warning:
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
708 - Danger:
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
709
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
710 Then, if the paragraph is too long, indent the text correctly.
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
711
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
712 ```markdown
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
713 Note: this is an information block that is too long to fit between the limits so
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
714 it is split and indented.
1a9a76f94955 Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents: 27
diff changeset
715 ```

mercurial