Mercurial > irccd

annotate STYLE.md @ 1201:67fa43998a91 default tip @

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: update copyright years
author David Demelier <markand@malikania.fr>
date Thu, 04 Jan 2024 10:39:43 +0100
parents 201ddc487807
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
1 irccd CODING STYLE
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
2 ==================
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
3
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
4 File content
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
5 ============
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
6
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
7 - Use UTF-8 charset,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
8 - Use Unix line endings,
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
9 - Never write two consecutives blank lines.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
10
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
11 Indent
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
12 ======
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
13
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
15 indenting code and have the advantage of being configurable. On the other hand
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
16 to keep code clean, you must align content with spaces only *within* a line.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
17
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
18 Note: we recommend 8 columns to avoid high number of indentations.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
19
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
20 Example (show whitespace in your editor)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
21
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
22 ```cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
23 class foo {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
24 public:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
25 enum type {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
26 dummy_value, // dummy comment
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
27 other_value // other comment
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
28 };
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
29
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
30 void long_function_name(very_long_type x1,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
31 very_long_type x2)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
32 {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
33 const map<string, string> m{
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
34 { "hostname", "127.0.0.1" },
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
35 { "port", "6667" }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
36 };
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
37 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
38 };
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
39 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
40
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
41 As a rule of thumb, tabs must always be all length.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
42
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
43 Example of incorrect usage:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
44
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
45 ```cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
46 { "hostname", "127.0.0.1" },
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
47 { "port", "6667" }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
48 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
49
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
50 This example will not align correctly if tabstops are not set to 8.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
51
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
52 C
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
53 =
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
54
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 Style
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 -----
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
57
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
58 - Do not exceed 80 columns.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
59
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 ### Braces
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
61
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 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
63 function definitions.
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
64
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
65 Do not put braces for single line statements.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
66
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
67 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
68 if (condition) {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
69 apply();
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
70 add();
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
71 } else
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
72 ok();
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
73
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
74 if (condition)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
75 validate();
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
76
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
77 if (foo)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
78 state = long + conditional + that + requires + several + lines +
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
79 to + complete;
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
80 ```
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
81
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
82 Functions require braces on their own lines.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
83
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
84 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
85 void
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
86 function()
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
87 {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
88 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
89 ```
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
90
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
91 Note: the type of a function is broken into its own line.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
93 ### Spaces
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
94
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
95 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
96 its argument.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
97
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
98 Normal function calls do not require it.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
99
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
100 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
101 if (foo)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
102 destroy(sizeof (int));
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
103 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
104
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
105 ### Pointers
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
106
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
107 Pointers are always next variable name.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
108
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
109 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
110 void
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
111 cleanup(struct owner *owner);
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
112 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
113
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
114 ### Typedefs
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
115
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
116 Do not use typedef for non-opaque objects. It is allowed for function pointers.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
117
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
118 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
119 struct pack {
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
120 int x;
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
121 int y;
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
122 };
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
123
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
124 typedef void (*logger)(const char *line);
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
125 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
126
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
127 Note: do never add `_t` suffix to typedef's.
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
128
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 ### Naming
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
130
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
131 - English names,
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
132 - No hungarian notation,
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
133
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
134 Almost everything is in `underscore_case` except macros and enumeration
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
135 constants.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
136
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
137 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
138 #if defined(FOO)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
139 # include <foo.hpp>
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
140 #endif
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
141
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
142 #define MAJOR 1
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
143 #define MINOR 0
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
144 #define PATCH 0
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
145
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
146 enum color {
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
147 COLOR_RED,
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
148 COLOR_GREEN,
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
149 COLOR_BLUE
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
150 };
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
151
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
152 void
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
153 add_widget(const struct widget *widget_to_add);
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
154 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
155
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
156 ### Header guards
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
157
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
158 Do not use `#pragma once`.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
159
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
160 Header guards are usually named `PROJECT_COMPONENT_FILENAME_H`.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
161
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
162 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
163 #ifndef FOO_COMMON_UTIL_H
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
164 #define FOO_COMMON_UTIL_H
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
165
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
166 #endif /* !FOO_COMMON_UTIL_HPP */
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
167 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
168
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
169 ### Enums
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
170
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
171 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
172 them as doxygen.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
173
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
174 Note: enumeration constants are prefixed with its name.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
175
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
176 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
177 enum color {
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
178 COLOR_RED,
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
179 COLOR_GREEN,
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
180 COLOR_BLUE
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
181 };
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
182 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
183
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
184 ### Switch
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
185
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
186 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
187 cases.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
188
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
189 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
190 switch (variable) {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
191 case foo:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
192 do_some_stuff();
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
193 break;
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
194 default:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
195 break;
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
196 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
197 ```
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
198
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
199 ### Files
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
200
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
201 - Use `.c` and `.h` as file extensions,
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
202 - Filenames are all lowercase.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
203
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
204 ### Comments
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
205
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
206 Avoid useless comments in source files. Comment complex things or why it is done
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
207 like this. Do not use `//` style comments in C.
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
208
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
209 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
210 /*
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
211 * Multi line comments look like
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
212 * this.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
213 */
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
214
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
215 /* Short comment. */
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
216 ```
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
217
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
218 Use `#if 0` to comment blocks of code.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
219
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
220 ```c
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
221 #if 0
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
222 broken_stuff();
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
223 #endif
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
224 ```
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
225
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
226 ### Includes
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
227
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
228 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
229
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
230 1. System headers (POSIX mostly)
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
231 2. C header
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
232 3. Third party libraries
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
233 4. Application headers in ""
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
234
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
235 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
236 #include <sys/types.h>
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
237 #include <sys/stat.h>
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
238 #include <string.h>
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
239
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
240 #include <libircclient.h>
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
241
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
242 #include "foo.h"
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
243 ```
409
c363c09e1f44 Misc: add CONTRIBUTE.md and STYLE.md
David Demelier <markand@malikania.fr>
parents:
diff changeset
244
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
245 Programming
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
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
248 ### C Standard
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
249
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
250 Use C11 standard without extensions.
533
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 ### Assertions
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
253
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
254 Use the `assert` macro from the assert.h header file to verify programming
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
255 errors.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
256
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
257 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
258 between the bounds of an array:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
259
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
260 ```c
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
261 int
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
262 get(struct data *data, unsigned index)
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
263 {
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
264 assert(index < data->length);
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
265
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
266 return data->buffer[index];
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
267 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
268 ```
533
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 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
271 must not be written that way:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
272
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
273 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
274 assert(listen(10));
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
275 ```
533
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 ### Return
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 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
280 more linear and not highly indented.
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
281
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
282 This code is preferred:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
283
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
284 ```c
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
285 if (a_condition_is_not_valid)
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
286 return false;
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
287 if (an_other_condition)
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
288 return false;
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
289
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
290 start();
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
291 save();
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
292
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
293 return true;
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
294 ```
533
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 Additional rules:
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
297
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
298 - Do never put parentheses between the returned value,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
299 - Do not put a else branch after a return.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
300
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
301 Shell
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
302 =====
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
303
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
304 Write POSIX shell only with no bash, zsh or any extension.
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
305
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
306 Style
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
307 -----
533
d5b6dd7c2311 Misc: update STYLE.md, closes #710
David Demelier <markand@malikania.fr>
parents: 409
diff changeset
308
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
309 - Try to keep lines shorter than 80 columns
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
310
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
311 Functions
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
312 ---------
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
313
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
314 Don't use `function` keyword, just keep the function name.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
315
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
316 ```sh
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
317 usage()
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
318 {
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
319 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
320 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
321
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
322 It's usually recommended to prefix functions names with the program name to
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
323 avoid collisions with global commands.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
324
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
325 ```sh
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
326 foo_clean()
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
327 {
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
328 }
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
329
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
330 foo_process()
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
331 {
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
332 }
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
333 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
334
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
335 Options
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
336 -------
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
337
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
338 For options, use `getopts` and prefer short options to long unless necessary.
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
339 Also set OPTERR=0 to avoid printing errors and do it yourself for UX
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
340 consistency.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
341
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
342 ```sh
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
343 OPTERR=0
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
344 while getopts "v" arg; do
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
345 case $arg in
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
346 v)
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
347 verbose=1
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
348 ;;
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
349 esac
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
350 done
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
351 ```
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
352
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
353 Naming
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
354 ------
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
355
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
356 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
357 local variables.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
358
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
359 CMake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
360 =====
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
361
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
362 Style
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
363 -----
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
364
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
365 - Try to keep lines shorter than 80 columns
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
366
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
367 ### Spaces
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
368
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
369 Each programming keyword (e.g. `if`, `foreach`, `while`) requires a single space
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
370 before its argument, otherwise write opening parenthese directly after.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
371
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
372 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
373 foreach (c ${COMPONENTS})
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
374 string(TOUPPER ${c} CMP)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
375
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
376 if (${WITH_${CMP}})
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
377 add_executable(${c} ${c}.cpp)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
378 endif ()
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
379 endforeach ()
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
380 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
381
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
382 ### Line breaks
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
383
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
384 When CMake lines goes too long, you should indent arguments at the same level,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
385 it's also common to see named argument values indented even more.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
386
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
387 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
388 set(
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
389 FILES
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
390 ${myapp_SOURCE_DIR}/main.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
391 ${myapp_SOURCE_DIR}/foo.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
392 ${myapp_SOURCE_DIR}/bar.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
393 )
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
394
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
395 command_with_lot_of_arguments(
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
396 TARGET foo
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
397 INSTALL On
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
398 SOURCES
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
399 ${myapp_SOURCE_DIR}/main.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
400 ${myapp_SOURCE_DIR}/foo.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
401 ${myapp_SOURCE_DIR}/bar.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
402 COMMENT "Some comment"
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
403 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
404
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
405 Modern CMake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
406 ------------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
407
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
408 CMake evolves over time, if you have read very old articles there is a chance
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
409 that what you have read is actually deprecated and replaced by other features.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
410 The following list is a short summary of modern CMake features that you must
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
411 use.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
412
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
413 ### Imported targets
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
414
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
415 When they are available, use imported targets rather than plain variables. They
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
416 offer complete dependency tracking with options and include directories as well.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
417
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
418 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
419 find_package(Boost COMPONENTS system)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
420 target_link_libraries(main Boost::system)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
421 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
422
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
423 ### Generator expressions
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
424
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
425 Use generator expressions when it make sense. For example you should use them
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
426 for variables that are not used at generation time (e.g CMAKE\_BUILD\_TYPE).
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
427
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
428 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
429 target_include_directories(
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
430 myapp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
431 $<BUILD_INTERFACE:${myapp_SOURCE_DIR}>
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
432 $<INSTALL_INTERFACE:include>
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
433 )
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
434 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
435
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
436 Warning: do never test against `CMAKE_BUILD_TYPE` in any CMakeLists.txt, IDEs
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
437 like Visual Studio will mismatch what you'll put in the conditions.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
438
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
439 ### Avoid global scoping
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
440
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
441 The following commands must be avoided as much as possible:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
442
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
443 - `link_directories`,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
444 - `link_libraries`,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
445 - `include_directories`,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
446 - `add_definitions`.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
447
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
448 They pollute the global namespace, all targets defined after these commands will
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
449 be built against those settings. Instead, you should use the per-targets
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
450 commands.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
451
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
452 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
453 target_include_directories(
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
454 mylib
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
455 PUBLIC
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
456 $<BUILD_INTERFACE:${mylib_SOURCE_DIR}>
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
457 $<INSTALL_INTERFACE:include>
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
458 )
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
459 target_link_libraries(mylib foo)
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
460 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
461
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
462 ### Defining sources
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
463
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
464 You MUST never use any kind of `file(GLOB)` commands to list sources for an
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
465 executable. CMake is designed to be re-called by itself only when required,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
466 having such a construct will not let CMake be able to detect if you have
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
467 added/removed files in your source directory. Instead, you MUST always specify
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
468 all source by hands.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
469
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
470 ```cmake
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
471 set(
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
472 FILES
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
473 ${myapp_SOURCE_DIR}/main.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
474 ${myapp_SOURCE_DIR}/a.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
475 ${myapp_SOURCE_DIR}/b.cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
476 )
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
477
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
478 add_executable(myapp ${FILES})
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
479 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
480
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
481 Markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
482 ========
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
483
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
484 Headers
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
485 -------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
486
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
487 For 1st and 2nd level headers, use `===` and `---` delimiters and underline the
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
488 whole title. Otherwise use `###`.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
489
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
490 ```markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
491 Top level title
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
492 ===============
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
493
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
494 Sub title
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
495 ---------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
496
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
497 ### Header 3
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
498
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
499 #### Header 4
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
500
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
501 ##### Header 5
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
502
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
503 ###### Header 6
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
504 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
505
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
506 Lists
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
507 -----
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
508
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
509 Use hyphens for unordered lists for consistency, do not indent top level lists,
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
510 then indent by two spaces each level
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
511
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
512 ```markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
513 - unordered list 1
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
514 - unordered list 2
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
515 - sub unordered item
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
516
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
517 1. unordered list 1
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
518 2. unordered list 2
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
519 2.1. sub unordered item
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
520 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
521
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
522 Code blocks
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
523 -----------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
524
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
525 You can use three backticks and the language specifier or just indent a block by
1008
201ddc487807 irccd: add irccd.conf file
David Demelier <markand@malikania.fr>
parents: 773
diff changeset
526 for leading tabs if you don't need syntax.
773
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
527
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
528 ```cpp
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
529 std::cout << "hello world" << std::endl;
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
530 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
531
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
532 And without syntax:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
533
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
534 ```markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
535 This is simple code block.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
536 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
537
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
538 Tables
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
539 ------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
540
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
541 Tables are supported and formatted as following:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
542
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
543 ```markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
544 | header 1 | header 2 |
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
545 |----------|----------|
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
546 | item 1 | item 2 |
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
547 ```
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
548
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
549 Alerts
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
550 ------
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
551
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
552 It's possible to prefix a paragraph by one of the following topic, it renders a
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
553 different block depending on the output format:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
554
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
555 - Note:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
556 - Warning:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
557 - Danger:
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
558
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
559 Then, if the paragraph is too long, indent the text correctly.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
560
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
561 ```markdown
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
562 Note: this is an information block that is too long to fit between the limits so
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
563 it is split and indented.
8c44bbcbbab9 Misc: style, cleanup and update
David Demelier <markand@malikania.fr>
parents: 635
diff changeset
564 ```