Mercurial > irccd

annotate STYLE.md @ 614:ebdc614db066

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Docs: get rid of metadata
author David Demelier <markand@malikania.fr>
date Sun, 17 Dec 2017 09:21:49 +0100
parents d5b6dd7c2311
children b452f5ce799c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
1 PROJECT NAME CODING STYLE
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
2 =========================
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
3
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
4 C++
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
5 ===
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
6
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 Style
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 -----
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
9
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 - Always use 4 spaces as indentation,
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
11 - Use UTF-8 charset,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
12 - Use Unix line endings,
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 - Do not exceed 120 characters for lines of code,
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
14 - Do not exceed 80 characters for comments,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
15 - Never write two blank consecutives blank lines,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
16 - Do not use bad words.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
17
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 ### Braces
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
19
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 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
21 function definitions.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
22
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
23 Do not put braces for single line statements except for clarity.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
24
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 if (condition) {
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 apply();
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 add();
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
28 } else
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 ok();
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
30
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
31 if (condition)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
32 validate();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
33
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
34 if (foo) {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
35 state = long + conditional + that + requires + several + lines +
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
36 to + complete;
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 }
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
38
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
39 Functions require braces on their own lines.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
40
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
41 void function()
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
42 {
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 }
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 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
46
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
47 sort([&] (auto&) {
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 return true;
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 });
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
50
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
51 ### Spaces
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
52
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
53 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
54 its argument.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
55
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
56 Normal function calls do not require it.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
57
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
58 if (foo)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
59 destroy(sizeof (int));
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
60
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
61 ### References and pointers
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
62
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
63 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
64
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
65 T& get(const std::string& name);
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
66
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
67 int* p = &x;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
68
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 ### Naming
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
70
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 - English names,
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
72 - Member variables have trailing underscore (e.g foo\_bar\_),
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 - No hungarian notation.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
74
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
75 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
76
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
77 #if defined(FOO)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
78 # include <foo.hpp>
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
79 #endif
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
80
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
81 namespace baz {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
82
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
83 class object {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
84 private:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
85 std::string name_;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
86
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
87 public:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
88 inline const std::string& name() const noexcept
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
89 {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
90 return name_;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
91 }
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
92 };
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
93
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
94 template <typename Archive>
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
95 void open(const Archive& ar)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
96 {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
97 bool is_valid = false;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
98 }
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
99
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
100 } // !baz
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
101
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
102 ### Header guards
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 Do not use `#pragma once`.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
105
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
106 Header guards are usually named **PROJECT_COMPONENT_FILENAME_HPP**.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
107
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
108 #ifndef FOO_COMMON_UTIL_HPP
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
109 #define FOO_COMMON_UTIL_HPP
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 #endif // !FOO_COMMON_UTIL_HPP
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 ### Enums
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
114
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
115 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
116 them as doxygen.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
117
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
118 Enum class are encouraged.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
119
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
120 enum class color {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
121 blue,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
122 red,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
123 green
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
124 };
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
125
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
126 ### Switch
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
127
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
128 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
129 cases.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
130
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
131 switch (variable) {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
132 case foo:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
133 do_some_stuff();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
134 break;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
135 default:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
136 break;
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 }
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
138
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 ### Files
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
140
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 - Use `.cpp` and `.hpp` as file extensions,
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 - Filenames are all lowercase.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
143
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 ### Comments
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
145
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 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
147 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
148 doxygen without exception.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
149
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 /*
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 * Multi line comments look like
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
152 * this.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
153 */
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
154
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
155 // Short comment
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
156
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
157 Use `#if 0` to comment blocks of code.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
158
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
159 #if 0
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
160 broken_stuff();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
161 #endif
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
162
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 ### Includes
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
164
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
165 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
166
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
167 1. C++ headers
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
168 2. C header
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 3. Third party libraries
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
170 4. Application headers in ""
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
171
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 #include <cstring>
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 #include <cerrno>
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
174
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
175 #include <sys/stat.h>
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
176
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
177 #include <libircclient.h>
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
178
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
179 #include "foo.h"
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
180
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
181 **Note**: always use C++ headers for C equivalent, stdio.h -> cstdio, etc.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
182
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
183 ### Commit messages
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
184
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
185 Commit messages are written using the following syntax:
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
186
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
187 Topic: short message less than 80 characters
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
188
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
189 Optional additional description if needed.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
190
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
191 Replace `Topic` with one of the following:
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
192
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
193 - **CMake**: for the build system,
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
194 - **Docs**: for the documentation,
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
195 - **Misc**: for miscellaneous files,
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
196 - **Tests**: for the unit tests.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
197
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
198 Programming
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
199 -----------
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
200
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
201 ### C language
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
202
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
203 Do not use old C stuff like `void *`, `srand/rand`, `printf` or anything that
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
204 can be rewritten in modern C++.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
205
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
206 ### RTTI
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
207
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
208 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
209 form.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
210
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
211 ### Arguments
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
212
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
213 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
214 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
215 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
216
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
217 std::cout << reverse(upper(clean(" hello world! "))) << std::endl;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
218
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
219 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
220 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
221
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
222 std::string clean(std::string input)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
223 {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
224 if (!input.empty() && input.back() == '\r')
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
225 input.pop_back();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
226
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
227 return input;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
228 }
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
229
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
230 Never pass primitive types as const value.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
231
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
232 ### Assertions
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
233
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
234 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
235 errors.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
236
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
237 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
238 between the bounds of an array:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
239
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
240 T& operator[](unsigned index)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
241 {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
242 assert(index < length_);
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
243
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
244 return data_[index];
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
245 }
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
246
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
247 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
248 must not be written that way:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
249
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
250 assert(listen(10));
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
251
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
252 ### Exceptions
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
253
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
254 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
255
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
256 - Failing to open a file,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
257 - I/O unexpected errors,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
258 - Parsing errors,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
259 - User errors.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
260
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
261 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
262 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
263 `std::exception`.
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 ### Error code
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 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
268 Error codes are allowed in Boost.Asio though.
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 ### Free functions
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 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
273 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
274
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
275 Example:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
276
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
277 namespace util {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
278
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
279 std::string clean(std::string input);
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
280
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
281 } // !util
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
282
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
283 ### Variables initialization
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
284
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
285 Use parentheses to initialize non primitive types:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
286
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
287 throw std::runtime_error("foo");
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
288
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
289 my_class obj("bar");
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
290
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
291 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
292 elision:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
293
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
294 std::vector<int> v{1, 2, 3};
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
295
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
296 foo({1, 2}); // type deduced
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
297
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
298 return { "true", false }; // std::pair returned
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 Use the assignment for primitive types:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
301
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
302 int x = 123;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
303 bool is_valid = true;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
304
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
305 ### Classes
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
306
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
307 Classes are usually defined in the following order:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
308
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
309 1. Public inner types (enums, classes),
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
310 2. Protected/private members
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
311 3. Public functions
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
312
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
313 class foo {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
314 public:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
315 enum class type {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
316 a,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
317 b
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
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
320 private:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
321 int member_{0};
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
322
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
323 public:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
324 void some_function();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
325 };
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
326
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
327 ### Structs
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
328
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
329 Do not use C structs unless you have very good reason to do so. If you want to
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
330 pack some data, just use `class` and make all fields public.
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 class point {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
333 public:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
334 int x{0};
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
335 int y{0};
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
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
338 ### Return
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
339
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
340 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
341 more linear and not highly indented.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
342
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
343 This code is preferred:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
344
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
345 if (a_condition_is_not_valid)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
346 return nullptr;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
347 if (an_other_condition)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
348 return nullptr;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
349
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
350 auto x = std::make_shared<object>();
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 x->start();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
353 x->save();
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
354
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
355 return x;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
356
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
357 Additional rules:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
358
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
359 - Do never put parentheses between the returned value,
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
360 - Do not put a else branch after a return.
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 ### Auto
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
363
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
364 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
365 change your code when your rename types.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
366
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
367 ````cpp
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
368 auto it = std::find_if(v.begin(), v.end(), [&] (const auto& obj) {
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
369 return obj.key() == "foo";
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
370 });
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
371
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
372 for (const auto& pair : a_map)
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
373 std::cout << pair.first << " = " << pair.second << std::endl;
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
374 ````
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
375
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
376 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
377
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
378 ````cpp
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
379 auto o = my_object("foo");
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
380 ````