irccd: STYLE.md annotate

annotate STYLE.md @ 829:963feffc07fe

irccd: fix invalid server load from json

author	David Demelier <markand@malikania.fr>
date	Thu, 07 Feb 2019 11:42:49 +0100
parents	8c44bbcbbab9
children	201ddc487807

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

Mercurial > irccd

annotate STYLE.md @ 829:963feffc07fe