Mercurial > template
annotate STYLE.md @ 52:02ec33e7ca7f default tip @
minor fixes
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Thu, 17 Dec 2020 10:33:19 +0100 |
| parents | 884ef6321dcc |
| children |
| rev | line source |
|---|---|
| 52 | 1 PROJECT_NAME CODING STYLE |
|
17
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 | 4 File content |
| 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, |
| 46 | 9 - Never write two consecutives blank lines. |
| 39 | 10 |
| 11 Indent | |
| 12 ====== | |
| 13 | |
| 14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for | |
| 15 indenting code and have the advantage of being configurable. On the other hand | |
| 16 to keep code clean, you must align content with spaces only *within* a line. | |
| 17 | |
| 18 Note: we recommend 8 columns to avoid high number of indentations. | |
| 19 | |
| 20 Example (show whitespace in your editor) | |
| 21 | |
| 22 ```cpp | |
| 23 class foo { | |
| 24 public: | |
| 25 enum type { | |
| 26 dummy_value, // dummy comment | |
| 27 other_value // other comment | |
| 28 }; | |
| 29 | |
| 30 void long_function_name(very_long_type x1, | |
| 31 very_long_type x2) | |
| 32 { | |
| 33 const map<string, string> m{ | |
| 34 { "hostname", "127.0.0.1" }, | |
| 35 { "port", "6667" } | |
| 36 }; | |
| 37 } | |
| 38 }; | |
| 39 ``` | |
| 40 | |
| 41 As a rule of thumb, tabs must always be all length. | |
| 42 | |
| 43 Example of incorrect usage: | |
| 44 | |
| 45 ```cpp | |
| 46 { "hostname", "127.0.0.1" }, | |
| 47 { "port", "6667" } | |
| 48 ``` | |
| 49 | |
| 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 |
| 51 | 52 C |
| 53 = | |
| 54 | |
| 55 Style | |
| 56 ----- | |
| 57 | |
| 58 - Do not exceed 80 columns. | |
| 59 | |
| 60 ### Braces | |
| 61 | |
| 62 Braces follow the K&R style, they are never placed on their own lines except for | |
| 63 function definitions. | |
| 64 | |
| 65 Do not put braces for single line statements. | |
| 66 | |
| 67 ```c | |
| 68 if (condition) { | |
| 69 apply(); | |
| 70 add(); | |
| 71 } else | |
| 72 ok(); | |
| 73 | |
| 74 if (condition) | |
| 75 validate(); | |
| 76 | |
| 77 if (foo) | |
| 78 state = long + conditional + that + requires + several + lines + | |
| 79 to + complete; | |
| 80 ``` | |
| 81 | |
| 82 Functions require braces on their own lines. | |
| 83 | |
| 84 ```c | |
| 85 void | |
| 86 function() | |
| 87 { | |
| 88 } | |
| 89 ``` | |
| 90 | |
| 91 Note: the type of a function is broken into its own line. | |
| 92 | |
| 93 ### Spaces | |
| 94 | |
| 95 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before | |
| 96 its argument. | |
| 97 | |
| 98 Normal function calls do not require it. | |
| 99 | |
| 100 ```c | |
| 101 if (foo) | |
| 102 destroy(sizeof (int)); | |
| 103 ``` | |
| 104 | |
| 105 ### Pointers | |
| 106 | |
| 107 Pointers are always next variable name. | |
| 108 | |
| 109 ```c | |
| 110 void | |
| 111 cleanup(struct owner *owner); | |
| 112 ``` | |
| 113 | |
| 114 ### Typedefs | |
| 115 | |
| 116 Do not use typedef for non-opaque objects. It is allowed for function pointers. | |
| 117 | |
| 118 ```c | |
| 119 struct pack { | |
| 120 int x; | |
| 121 int y; | |
| 122 }; | |
| 123 | |
| 124 typedef void (*logger)(const char *line); | |
| 125 ``` | |
| 126 | |
| 127 Note: do never add `_t` suffix to typedef's. | |
| 128 | |
| 129 ### Naming | |
| 130 | |
| 131 - English names, | |
| 132 - No hungarian notation, | |
| 133 | |
| 134 Almost everything is in `underscore_case` except macros and enumeration | |
| 135 constants. | |
| 136 | |
| 137 ```c | |
| 138 #if defined(FOO) | |
| 139 # include <foo.hpp> | |
| 140 #endif | |
| 141 | |
| 142 #define MAJOR 1 | |
| 143 #define MINOR 0 | |
| 144 #define PATCH 0 | |
| 145 | |
| 146 enum color { | |
| 147 COLOR_RED, | |
| 148 COLOR_GREEN, | |
| 149 COLOR_BLUE | |
| 150 }; | |
| 151 | |
| 152 void | |
| 153 add_widget(const struct widget *widget_to_add); | |
| 154 ``` | |
| 155 | |
| 156 ### Header guards | |
| 157 | |
| 158 Do not use `#pragma once`. | |
| 159 | |
| 160 Header guards are usually named `PROJECT_COMPONENT_FILENAME_H`. | |
| 161 | |
| 162 ```c | |
| 163 #ifndef FOO_COMMON_UTIL_H | |
| 164 #define FOO_COMMON_UTIL_H | |
| 165 | |
| 166 #endif /* !FOO_COMMON_UTIL_HPP */ | |
| 167 ``` | |
| 168 | |
| 169 ### Enums | |
| 170 | |
| 171 Enumerations constants are always defined in separate line to allow commenting | |
| 172 them as doxygen. | |
| 173 | |
| 174 Note: enumeration constants are prefixed with its name. | |
| 175 | |
| 176 ```c | |
| 177 enum color { | |
| 178 COLOR_RED, | |
| 179 COLOR_GREEN, | |
| 180 COLOR_BLUE | |
| 181 }; | |
| 182 ``` | |
| 183 | |
| 184 ### Switch | |
| 185 | |
| 186 In a switch case statement, you **must** not declare variables and not indent | |
| 187 cases. | |
| 188 | |
| 189 ```c | |
| 190 switch (variable) { | |
| 191 case foo: | |
| 192 do_some_stuff(); | |
| 193 break; | |
| 194 default: | |
| 195 break; | |
| 196 } | |
| 197 ``` | |
| 198 | |
| 199 ### Files | |
| 200 | |
| 201 - Use `.c` and `.h` as file extensions, | |
| 202 - Filenames are all lowercase. | |
| 203 | |
| 204 ### Comments | |
| 205 | |
| 206 Avoid useless comments in source files. Comment complex things or why it is done | |
| 52 | 207 like this. Do not use `//` style comments in C. |
| 51 | 208 |
| 209 ```c | |
| 210 /* | |
| 211 * Multi line comments look like | |
| 212 * this. | |
| 213 */ | |
| 214 | |
| 52 | 215 /* Short comment. */ |
| 51 | 216 ``` |
| 217 | |
| 218 Use `#if 0` to comment blocks of code. | |
| 219 | |
| 220 ```c | |
| 221 #if 0 | |
| 222 broken_stuff(); | |
| 223 #endif | |
| 224 ``` | |
| 225 | |
| 226 ### Includes | |
| 227 | |
| 228 The includes should always come in the following order. | |
| 229 | |
| 230 1. System headers (POSIX mostly) | |
| 231 2. C header | |
| 232 3. Third party libraries | |
| 233 4. Application headers in "" | |
| 234 | |
| 235 ```c | |
| 236 #include <sys/types.h> | |
| 237 #include <sys/stat.h> | |
| 238 #include <string.h> | |
| 239 | |
| 240 #include <libircclient.h> | |
| 241 | |
| 242 #include "foo.h" | |
| 243 ``` | |
| 244 | |
| 245 Programming | |
| 246 ----------- | |
| 247 | |
| 248 ### C Standard | |
| 249 | |
| 52 | 250 Use C11 standard without extensions. |
| 51 | 251 |
| 252 ### Assertions | |
| 253 | |
| 254 Use the `assert` macro from the assert.h header file to verify programming | |
| 255 errors. | |
| 256 | |
| 257 For example, you may use `assert` to verify that the developer access the data | |
| 258 between the bounds of an array: | |
| 259 | |
| 260 ```c | |
| 261 int | |
| 262 get(struct data *data, unsigned index) | |
| 263 { | |
| 264 assert(index < data->length); | |
| 265 | |
| 266 return data->buffer[index]; | |
| 267 } | |
| 268 ``` | |
| 269 | |
| 270 The `assert` macro is not meant to check that a function succeeded, this code | |
| 271 must not be written that way: | |
| 272 | |
| 273 ```c | |
| 274 assert(listen(10)); | |
| 275 ``` | |
| 276 | |
| 277 ### Return | |
| 278 | |
| 279 The preferred style is to return early in case of errors. That makes the code | |
| 280 more linear and not highly indented. | |
| 281 | |
| 282 This code is preferred: | |
| 283 | |
| 284 ```c | |
| 285 if (a_condition_is_not_valid) | |
| 286 return false; | |
| 287 if (an_other_condition) | |
| 288 return false; | |
| 289 | |
| 290 start(); | |
| 291 save(); | |
| 292 | |
| 293 return true; | |
| 294 ``` | |
| 295 | |
| 296 Additional rules: | |
| 297 | |
| 298 - Do never put parentheses between the returned value, | |
| 299 - Do not put a else branch after a return. | |
| 300 | |
|
17
314e8bb2659a
Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents:
16
diff
changeset
|
301 C++ |
|
314e8bb2659a
Rename STYLE_CPP.md to STYLE.md
David Demelier <markand@malikania.fr>
parents:
16
diff
changeset
|
302 === |
| 0 | 303 |
| 304 Style | |
| 305 ----- | |
| 306 | |
| 39 | 307 - Do not exceed 120 columns for lines of code, |
| 308 - Do not exceed 80 columns for comments, | |
| 0 | 309 |
| 310 ### Braces | |
| 311 | |
| 312 Braces follow the K&R style, they are never placed on their own lines except for | |
| 313 function definitions. | |
| 314 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
315 Do not put braces for single line statements. |
| 10 | 316 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
317 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
318 if (condition) { |
| 39 | 319 apply(); |
| 320 add(); | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
321 } else |
| 39 | 322 ok(); |
| 10 | 323 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
324 if (condition) |
| 39 | 325 validate(); |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
326 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
327 if (foo) |
| 39 | 328 state = long + conditional + that + requires + several + lines + |
| 329 to + complete; | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
330 ``` |
| 0 | 331 |
| 10 | 332 Functions require braces on their own lines. |
| 333 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
334 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
335 void function() |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
336 { |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
337 } |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
338 ``` |
| 0 | 339 |
| 340 And a lambda has its braces on the same lines too: | |
| 341 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
342 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
343 sort([&] (auto&) { |
| 39 | 344 return true; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
345 }); |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
346 ``` |
| 0 | 347 |
| 348 ### Spaces | |
| 349 | |
| 350 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before | |
| 351 its argument. | |
| 352 | |
| 353 Normal function calls do not require it. | |
| 354 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
355 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
356 if (foo) |
| 39 | 357 destroy(sizeof (int)); |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
358 ``` |
| 0 | 359 |
| 360 ### References and pointers | |
| 361 | |
| 362 References and pointers are always next to the type name and not the variable. | |
| 363 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
364 ```cpp |
| 34 | 365 auto get(const std::string& name) -> T&; |
| 0 | 366 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
367 int* p = &x; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
368 ``` |
| 0 | 369 |
| 34 | 370 ### Trailing return syntax |
| 371 | |
| 372 We use trailing return syntax everywhere, it has the following benefits: | |
| 373 | |
| 374 - Inner types don't need to be prefixed by class name, | |
| 375 - Functions are kept aligned correctly, focusing on the function name. | |
| 376 | |
| 377 ```cpp | |
| 378 auto func() -> std::string; | |
| 379 ``` | |
| 380 | |
| 0 | 381 ### Naming |
| 382 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
383 - English names, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
384 - 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
|
385 - No hungarian notation. |
| 0 | 386 |
| 387 Everything is in `underscore_case` except template parameters and macros. | |
| 388 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
389 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
390 #if defined(FOO) |
| 39 | 391 # include <foo.hpp> |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
392 #endif |
| 0 | 393 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
394 namespace baz { |
| 0 | 395 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
396 class object { |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
397 private: |
| 39 | 398 std::string name_; |
| 0 | 399 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
400 public: |
| 39 | 401 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
|
402 }; |
| 0 | 403 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
404 template <typename Archive> |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
405 void open(const Archive& ar) |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
406 { |
| 39 | 407 bool is_valid = false; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
408 } |
| 0 | 409 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
410 } // !baz |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
411 ``` |
| 0 | 412 |
| 413 ### Header guards | |
| 414 | |
| 415 Do not use `#pragma once`. | |
| 416 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
417 Header guards are usually named `PROJECT_COMPONENT_FILENAME_HPP`. |
| 0 | 418 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
419 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
420 #ifndef FOO_COMMON_UTIL_HPP |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
421 #define FOO_COMMON_UTIL_HPP |
| 0 | 422 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
423 #endif // !FOO_COMMON_UTIL_HPP |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
424 ``` |
| 0 | 425 |
| 426 ### Enums | |
| 427 | |
| 428 Enumerations constants are always defined in separate line to allow commenting | |
| 429 them as doxygen. | |
| 430 | |
| 431 Enum class are encouraged. | |
| 432 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
433 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
434 enum class color { |
| 39 | 435 blue, |
| 436 red, | |
| 437 green | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
438 }; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
439 ``` |
| 0 | 440 |
|
16
780c138ab41d
Add a note about switch
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
441 ### Switch |
|
780c138ab41d
Add a note about switch
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
442 |
|
780c138ab41d
Add a note about switch
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
443 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
|
444 cases. |
|
780c138ab41d
Add a note about switch
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
445 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
446 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
447 switch (variable) { |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
448 case foo: |
| 39 | 449 do_some_stuff(); |
| 450 break; | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
451 default: |
| 39 | 452 break; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
453 } |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
454 ``` |
|
16
780c138ab41d
Add a note about switch
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
455 |
| 0 | 456 ### Files |
| 457 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
458 - 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
|
459 - Filenames are all lowercase. |
| 0 | 460 |
| 461 ### Comments | |
| 462 | |
| 463 Avoid useless comments in source files. Comment complex things or why it is done | |
| 52 | 464 like this. |
| 0 | 465 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
466 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
467 /* |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
468 * Multi line comments look like |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
469 * this. |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
470 */ |
| 0 | 471 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
472 // Short comment |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
473 ``` |
| 0 | 474 |
| 2 | 475 Use `#if 0` to comment blocks of code. |
| 476 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
477 ```cpp |
| 2 | 478 #if 0 |
| 39 | 479 broken_stuff(); |
| 2 | 480 #endif |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
481 ``` |
| 2 | 482 |
| 0 | 483 ### Includes |
| 484 | |
| 485 The includes should always come in the following order. | |
| 486 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
487 1. C++ headers |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
488 2. C header |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
489 3. Third party libraries |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
490 4. Application headers in "" |
| 0 | 491 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
492 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
493 #include <cstring> |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
494 #include <cerrno> |
| 0 | 495 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
496 #include <sys/stat.h> |
| 0 | 497 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
498 #include <libircclient.h> |
| 0 | 499 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
500 #include "foo.h" |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
501 ``` |
| 0 | 502 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
503 Note: always use C++ headers for C equivalent, stdio.h -> cstdio, etc. |
| 0 | 504 |
| 505 Programming | |
| 506 ----------- | |
| 507 | |
| 508 ### C language | |
| 509 | |
| 39 | 510 Do not use old C stuff like `void*`, `srand/rand`, `printf` or anything that |
| 0 | 511 can be rewritten in modern C++. |
| 512 | |
| 513 ### RTTI | |
| 514 | |
| 515 Usage of `dynamic_cast` and `typeid` are completely disallowed in any shape of | |
| 516 form. | |
| 517 | |
| 518 ### Arguments | |
| 519 | |
| 520 It is recommended to pass parameters by value or const reference. Usage of | |
| 521 non-const reference as output parameter is **discouraged** and should be avoided | |
| 522 in many case because it does not allow chaining of expressions like: | |
| 523 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
524 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
525 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
|
526 ``` |
| 0 | 527 |
| 528 If your function is designed to return a modified value passed as argument, it | |
| 529 is better to take it by value and modify it directly. | |
| 530 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
531 ```cpp |
| 34 | 532 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
|
533 { |
| 39 | 534 if (!input.empty() && input.back() == '\r') |
| 535 input.pop_back(); | |
| 0 | 536 |
| 39 | 537 return input; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
538 } |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
539 ``` |
| 0 | 540 |
| 541 Never pass primitive types as const value. | |
| 542 | |
| 543 ### Assertions | |
| 544 | |
| 545 Use the `assert` macro from the cassert header file to verify programming | |
| 546 errors. | |
| 547 | |
| 548 For example, you may use `assert` to verify that the developer access the data | |
| 549 between the bounds of an array: | |
| 550 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
551 ```cpp |
| 34 | 552 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
|
553 { |
| 39 | 554 assert(index < length_); |
| 0 | 555 |
| 39 | 556 return data_[index]; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
557 } |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
558 ``` |
| 0 | 559 |
| 560 The `assert` macro is not meant to check that a function succeeded, this code | |
| 561 must not be written that way: | |
| 562 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
563 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
564 assert(listen(10)); |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
565 ``` |
| 0 | 566 |
| 567 ### Exceptions | |
| 568 | |
| 569 You must use exceptions to indicate an error that was unexpected such as: | |
| 570 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
571 - Failing to open a file, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
572 - I/O unexpected errors, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
573 - Parsing errors, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
574 - User errors. |
| 0 | 575 |
| 576 You may use the C++ standard exceptions defined in the stdexcept header but if | |
| 577 you need to carry more data within your exception, you should derive from | |
| 578 `std::exception`. | |
| 579 | |
|
14
55bb3689093f
Add chapter about error codes
David Demelier <markand@malikania.fr>
parents:
13
diff
changeset
|
580 ### Error code |
|
55bb3689093f
Add chapter about error codes
David Demelier <markand@malikania.fr>
parents:
13
diff
changeset
|
581 |
|
55bb3689093f
Add chapter about error codes
David Demelier <markand@malikania.fr>
parents:
13
diff
changeset
|
582 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
|
583 Error codes are allowed in Boost.Asio though. |
|
55bb3689093f
Add chapter about error codes
David Demelier <markand@malikania.fr>
parents:
13
diff
changeset
|
584 |
| 0 | 585 ### Free functions |
| 586 | |
| 587 Basic utility functions should be defined in a namespace as a free function not | |
| 588 as a static member function, we're doing C++ not Java. | |
| 589 | |
| 590 Example: | |
| 591 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
592 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
593 namespace util { |
| 0 | 594 |
| 39 | 595 auto clean(std::string input) -> std::string; |
| 0 | 596 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
597 } // !util |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
598 ``` |
| 0 | 599 |
| 600 ### Variables initialization | |
| 601 | |
| 602 Use parentheses to initialize non primitive types: | |
| 603 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
604 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
605 throw std::runtime_error("foo"); |
| 0 | 606 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
607 my_class obj("bar"); |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
608 ``` |
| 0 | 609 |
| 610 Use brace initialization when you want to use an initializer list, type | |
| 611 elision: | |
| 612 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
613 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
614 std::vector<int> v{1, 2, 3}; |
| 0 | 615 |
| 52 | 616 foo({1, 2}); // type deduced |
| 0 | 617 |
| 52 | 618 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
|
619 ``` |
| 0 | 620 |
| 621 Use the assignment for primitive types: | |
| 622 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
623 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
624 int x = 123; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
625 bool is_valid = true; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
626 ``` |
| 0 | 627 |
| 628 ### Classes | |
| 629 | |
| 630 Classes are usually defined in the following order: | |
| 631 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
632 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
|
633 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
|
634 3. Public static functions. |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
635 3. Public member functions |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
636 4. Public virtual functions. |
| 0 | 637 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
638 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
639 class foo { |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
640 public: |
| 39 | 641 enum class type { |
| 642 a, | |
| 643 b | |
| 644 }; | |
| 0 | 645 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
646 private: |
| 39 | 647 int member_{0}; |
| 0 | 648 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
649 public: |
| 39 | 650 void some_function(); |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
651 }; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
652 ``` |
| 0 | 653 |
| 654 ### Structs | |
| 655 | |
|
31
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
656 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
|
657 invariants. For example PODs and traits match this criteria: |
| 0 | 658 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
659 ```cpp |
|
31
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
660 struct point { |
| 39 | 661 int x{0}; |
| 662 int y{0}; | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
663 }; |
|
31
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
664 |
|
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
665 template <> |
|
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
666 struct info_traits<point> { |
| 39 | 667 template <typename Archive> |
| 668 static void serialize(Archive& ar, const point& point) | |
| 669 { | |
| 670 ar.write(point.x); | |
| 671 ar.write(point.y); | |
| 672 } | |
|
31
5ea2876ac37a
Relax usage of structs
David Demelier <markand@malikania.fr>
parents:
28
diff
changeset
|
673 }; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
674 ``` |
| 0 | 675 |
| 676 ### Return | |
| 677 | |
| 678 The preferred style is to return early in case of errors. That makes the code | |
| 679 more linear and not highly indented. | |
| 680 | |
| 681 This code is preferred: | |
| 682 | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
683 ```cpp |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
684 if (a_condition_is_not_valid) |
| 39 | 685 return nullptr; |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
686 if (an_other_condition) |
| 39 | 687 return nullptr; |
| 0 | 688 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
689 auto x = std::make_shared<object>(); |
| 0 | 690 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
691 x->start(); |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
692 x->save(); |
| 0 | 693 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
694 return x; |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
695 ``` |
| 0 | 696 |
|
1
9bf9b4634339
Update return statement
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
697 Additional rules: |
|
9bf9b4634339
Update return statement
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
698 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
699 - 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
|
700 - Do not put a else branch after a return. |
|
13
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
701 |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
702 ### Auto |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
703 |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
704 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
|
705 change your code when your rename types. |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
706 |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
707 ```cpp |
|
13
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
708 auto it = std::find_if(v.begin(), v.end(), [&] (const auto& obj) { |
| 39 | 709 return obj.key() == "foo"; |
|
13
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
710 }); |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
711 |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
712 for (const auto& pair : a_map) |
| 39 | 713 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
|
714 ``` |
|
13
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
715 |
|
4d6bf8b3446d
Add chapter about auto
David Demelier <markand@malikania.fr>
parents:
12
diff
changeset
|
716 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
|
717 |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
718 ```cpp |
| 34 | 719 auto o = my_object("foo"); |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
720 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
721 |
|
32
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
722 ### String views |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
723 |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
724 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
|
725 includes: temporary arguments, return values, compile time constants. |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
726 |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
727 ```cpp |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
728 const std::string_view version("1.0"); |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
729 |
|
33
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
730 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
|
731 { |
| 39 | 732 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
|
733 } |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
734 ``` |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
735 |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
736 ### Optional values |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
737 |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
738 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
|
739 searching a value that may not exist. |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
740 |
|
793a60620477
Add paragraph about std::optional
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
741 ```cpp |
|
32
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
742 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
|
743 { |
| 39 | 744 if (auto it = foo.find(id); it != foo.end()) |
| 745 return it->second; | |
|
32
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
746 |
| 39 | 747 return std::nullopt; |
|
32
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
748 } |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
749 ``` |
|
651aee870e36
Add paragraph about std::string_view
David Demelier <markand@malikania.fr>
parents:
31
diff
changeset
|
750 |
|
35
6114710feda7
Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents:
34
diff
changeset
|
751 ### Avoid definitions in headers |
|
6114710feda7
Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents:
34
diff
changeset
|
752 |
|
6114710feda7
Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents:
34
diff
changeset
|
753 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
|
754 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
|
755 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
|
756 header rather than a source file. |
|
6114710feda7
Add paragraph about code in headers
David Demelier <markand@malikania.fr>
parents:
34
diff
changeset
|
757 |
|
44
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
758 Shell |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
759 ===== |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
760 |
| 47 | 761 Write POSIX shell only with no bash, zsh or any extension. |
|
44
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
762 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
763 Style |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
764 ----- |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
765 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
766 - Try to keep lines shorter than 80 columns |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
767 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
768 Functions |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
769 --------- |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
770 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
771 Don't use `function` keyword, just keep the function name. |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
772 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
773 ```sh |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
774 usage() |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
775 { |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
776 } |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
777 ``` |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
778 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
779 It's usually recommended to prefix functions names with the program name to |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
780 avoid collisions with global commands. |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
781 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
782 ```sh |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
783 foo_clean() |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
784 { |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
785 } |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
786 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
787 foo_process() |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
788 { |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
789 } |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
790 ``` |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
791 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
792 Options |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
793 ------- |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
794 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
795 For options, use `getopts` and prefer short options to long unless necessary. |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
796 Also set OPTERR=0 to avoid printing errors and do it yourself for UX |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
797 consistency. |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
798 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
799 ```sh |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
800 OPTERR=0 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
801 while getopts "v" arg; do |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
802 case $arg in |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
803 v) |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
804 verbose=1 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
805 ;; |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
806 esac |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
807 done |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
808 ``` |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
809 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
810 Naming |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
811 ------ |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
812 |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
813 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
814 local variables. |
|
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
815 |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
816 CMake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
817 ===== |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
818 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
819 Style |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
820 ----- |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
821 |
|
44
1230716dd497
Add section about shell
David Demelier <markand@malikania.fr>
parents:
40
diff
changeset
|
822 - Try to keep lines shorter than 80 columns |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
823 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
824 ### Spaces |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
825 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
826 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
|
827 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
|
828 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
829 ```cmake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
830 foreach (c ${COMPONENTS}) |
| 39 | 831 string(TOUPPER ${c} CMP) |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
832 |
| 39 | 833 if (${WITH_${CMP}}) |
| 834 add_executable(${c} ${c}.cpp) | |
| 835 endif () | |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
836 endforeach () |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
837 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
838 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
839 ### Line breaks |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
840 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
841 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
|
842 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
|
843 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
844 ```cmake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
845 set( |
| 39 | 846 FILES |
| 847 ${myapp_SOURCE_DIR}/main.cpp | |
| 848 ${myapp_SOURCE_DIR}/foo.cpp | |
| 849 ${myapp_SOURCE_DIR}/bar.cpp | |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
850 ) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
851 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
852 command_with_lot_of_arguments( |
| 39 | 853 TARGET foo |
| 854 INSTALL On | |
| 855 SOURCES | |
| 856 ${myapp_SOURCE_DIR}/main.cpp | |
| 857 ${myapp_SOURCE_DIR}/foo.cpp | |
| 858 ${myapp_SOURCE_DIR}/bar.cpp | |
| 859 COMMENT "Some comment" | |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
860 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
861 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
862 Modern CMake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
863 ------------ |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
864 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
865 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
|
866 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
|
867 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
|
868 use. |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
869 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
870 ### Imported targets |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
871 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
872 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
|
873 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
|
874 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
875 ```cmake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
876 find_package(Boost COMPONENTS system) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
877 target_link_libraries(main Boost::system) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
878 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
879 |
|
40
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
880 ### Generator expressions |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
881 |
|
40
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
882 Use generator expressions when it make sense. For example you should use them |
|
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
883 for variables that are not used at generation time (e.g CMAKE\_BUILD\_TYPE). |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
884 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
885 ```cmake |
|
40
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
886 target_include_directories( |
| 39 | 887 myapp |
|
40
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
888 $<BUILD_INTERFACE:${myapp_SOURCE_DIR}> |
|
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
889 $<INSTALL_INTERFACE:include> |
|
cb25a20c1fc9
Update generator expressions paragraph
David Demelier <markand@malikania.fr>
parents:
39
diff
changeset
|
890 ) |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
891 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
892 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
893 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
|
894 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
|
895 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
896 ### Avoid global scoping |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
897 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
898 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
|
899 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
900 - `link_directories`, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
901 - `link_libraries`, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
902 - `include_directories`, |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
903 - `add_definitions`. |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
904 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
905 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
|
906 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
|
907 commands. |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
908 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
909 ```cmake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
910 target_include_directories( |
| 39 | 911 mylib |
| 912 PUBLIC | |
| 913 $<BUILD_INTERFACE:${mylib_SOURCE_DIR}> | |
| 914 $<INSTALL_INTERFACE:include> | |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
915 ) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
916 target_link_libraries(mylib foo) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
917 ``` |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
918 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
919 ### Defining sources |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
920 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
921 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
|
922 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
|
923 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
|
924 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
|
925 all source by hands. |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
926 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
927 ```cmake |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
928 set( |
| 39 | 929 FILES |
| 930 ${myapp_SOURCE_DIR}/main.cpp | |
| 931 ${myapp_SOURCE_DIR}/a.cpp | |
| 932 ${myapp_SOURCE_DIR}/b.cpp | |
|
25
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
933 ) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
934 |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
935 add_executable(myapp ${FILES}) |
|
9573e6c9ac97
Add CMake guide in STYLE.md
David Demelier <markand@malikania.fr>
parents:
17
diff
changeset
|
936 ``` |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
937 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
938 Markdown |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
939 ======== |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
940 |
|
37
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
941 Headers |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
942 ------- |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
943 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
944 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
|
945 whole title. Otherwise use `###`. |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
946 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
947 ```markdown |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
948 Top level title |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
949 =============== |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
950 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
951 Sub title |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
952 --------- |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
953 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
954 ### Header 3 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
955 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
956 #### Header 4 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
957 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
958 ##### Header 5 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
959 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
960 ###### Header 6 |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
961 ``` |
|
a77a41f83ebb
Add header style to markdown
David Demelier <markand@malikania.fr>
parents:
35
diff
changeset
|
962 |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
963 Lists |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
964 ----- |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
965 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
966 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
|
967 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
|
968 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
969 ```markdown |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
970 - unordered list 1 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
971 - unordered list 2 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
972 - sub unordered item |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
973 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
974 1. unordered list 1 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
975 2. unordered list 2 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
976 2.1. sub unordered item |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
977 ``` |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
978 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
979 Code blocks |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
980 ----------- |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
981 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
982 You can use three backticks and the language specifier or just indent a block by |
| 52 | 983 for leading tabs if you don't need syntax. |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
984 |
| 39 | 985 ```cpp |
| 986 std::cout << "hello world" << std::endl; | |
| 987 ``` | |
|
27
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
988 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
989 And without syntax: |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
990 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
991 ```markdown |
| 39 | 992 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
|
993 ``` |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
994 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
995 Tables |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
996 ------ |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
997 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
998 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
|
999 |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
1000 ```markdown |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
1001 | header 1 | header 2 | |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
1002 |----------|----------| |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
1003 | item 1 | item 2 | |
|
0706d01e073f
Update markdown convention and add it to STYLE.md
David Demelier <markand@malikania.fr>
parents:
25
diff
changeset
|
1004 ``` |
|
28
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1005 |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1006 Alerts |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1007 ------ |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1008 |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1009 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
|
1010 different block depending on the output format: |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1011 |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1012 - Note: |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1013 - Warning: |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1014 - Danger: |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1015 |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1016 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
|
1017 |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1018 ```markdown |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1019 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
|
1020 it is split and indented. |
|
1a9a76f94955
Add alerts in markdown style
David Demelier <markand@malikania.fr>
parents:
27
diff
changeset
|
1021 ``` |