Mercurial > irccd
annotate STYLE.md @ 655:cda30ca5bb76
Irccd: style (controller) #782
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 27 Mar 2018 20:30:59 +0200 |
parents | b452f5ce799c |
children | 8c44bbcbbab9 |
rev | line source |
---|---|
635 | 1 irccd CODING STYLE |
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 ```` |