Mercurial > molko
annotate STYLE.md @ 13:c188e9603faf
misc: add basic documentation files
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 07 Jan 2020 21:34:03 +0100 |
parents | |
children | 98e091b9251e |
rev | line source |
---|---|
13
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 Molko's Adventure CODING STYLE |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 ============================== |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 File content |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 ============ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 - Use UTF-8 charset, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 - Use Unix line endings, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 - Never write two consecutives blank lines. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 Indent |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 ====== |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 indenting code and have the advantage of being configurable. On the other hand |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 to keep code clean, you must align content with spaces only *within* a line. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 Note: we recommend 8 columns to avoid high number of indentations. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 Example (show whitespace in your editor) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 ```cpp |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 class foo { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 public: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 enum type { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 dummy_value, // dummy comment |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 other_value // other comment |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 void long_function_name(very_long_type x1, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 very_long_type x2) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 const map<string, string> m{ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 { "hostname", "127.0.0.1" }, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 { "port", "6667" } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 As a rule of thumb, tabs must always be all length. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 Example of incorrect usage: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 ```cpp |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 { "hostname", "127.0.0.1" }, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 { "port", "6667" } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 This example will not align correctly if tabstops are not set to 8. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 C |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 = |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 Style |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 ----- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 - Do not exceed 80 columns. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 ### Braces |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 |
c188e9603faf
misc: add basic documentation files
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 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 function definitions. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 Do not put braces for single line statements. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 if (condition) { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 apply(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 add(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 } else |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 ok(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
73 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
74 if (condition) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
75 validate(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
77 if (foo) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
78 state = long + conditional + that + requires + several + lines + |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
79 to + complete; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
80 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
81 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
82 Functions require braces on their own lines. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
83 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
84 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
85 void |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
86 function() |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
87 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
88 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
89 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
90 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
91 Note: the type of a function is broken into its own line. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
92 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
93 ### Spaces |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
94 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
95 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
96 its argument. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
97 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
98 Normal function calls do not require it. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
99 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
100 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
101 if (foo) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
102 destroy(sizeof (int)); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
103 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
104 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
105 ### Pointers |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
106 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
107 Pointers are always next variable name. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
108 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
109 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
110 void |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
111 cleanup(struct owner *owner); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
112 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
113 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
114 ### Typedefs |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
115 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
116 Do not use typedef for non-opaque objects. It is allowed for function pointers. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
117 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
118 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
119 struct pack { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
120 int x; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
121 int y; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
122 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
123 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
124 typedef void (*logger)(const char *line); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
125 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
126 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
127 Note: do never add `_t` suffix to typedef's. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
128 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
129 ### Naming |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
130 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
131 - English names, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
132 - No hungarian notation, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
133 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
134 Almost everything is in `underscore_case` except macros and enumeration |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
135 constants. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
136 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
137 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
138 #if defined(FOO) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
139 # include <foo.hpp> |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
140 #endif |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
141 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
142 #define MAJOR 1 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
143 #define MINOR 0 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
144 #define PATCH 0 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
145 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
146 enum color { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
147 COLOR_RED, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
148 COLOR_GREEN, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
149 COLOR_BLUE |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
150 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
151 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
152 void |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
153 add_widget(const struct widget *widget_to_add); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
154 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
155 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
156 ### Header guards |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
157 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
158 Do not use `#pragma once`. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
159 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
160 Header guards are usually named `PROJECT_COMPONENT_FILENAME_H`. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
161 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
162 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
163 #ifndef FOO_COMMON_UTIL_H |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
164 #define FOO_COMMON_UTIL_H |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
165 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
166 #endif /* !FOO_COMMON_UTIL_HPP */ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
167 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
168 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
169 ### Enums |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
170 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
171 Enumerations constants are always defined in separate line to allow commenting |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
172 them as doxygen. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
173 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
174 Note: enumeration constants are prefixed with its name. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
175 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
176 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
177 enum color { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
178 COLOR_RED, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
179 COLOR_GREEN, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
180 COLOR_BLUE |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
181 }; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
182 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
183 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
184 ### Switch |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
185 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
186 In a switch case statement, you **must** not declare variables and not indent |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
187 cases. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
188 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
189 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
190 switch (variable) { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
191 case foo: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
192 do_some_stuff(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
193 break; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
194 default: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
195 break; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
196 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
197 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
198 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
199 ### Files |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
200 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
201 - Use `.c` and `.h` as file extensions, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
202 - Filenames are all lowercase. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
203 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
204 ### Comments |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
205 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
206 Avoid useless comments in source files. Comment complex things or why it is done |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
207 like this. However any public function in the .h **must** be documented as |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
208 doxygen without exception. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
209 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
210 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
211 /* |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
212 * Multi line comments look like |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
213 * this. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
214 */ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
215 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
216 // Short comment |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
217 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
218 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
219 Use `#if 0` to comment blocks of code. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
220 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
221 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
222 #if 0 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
223 broken_stuff(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
224 #endif |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
225 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
226 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
227 ### Includes |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
228 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
229 The includes should always come in the following order. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
230 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
231 1. System headers (POSIX mostly) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
232 2. C header |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
233 3. Third party libraries |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
234 4. Application headers in "" |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
235 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
236 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
237 #include <sys/types.h> |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
238 #include <sys/stat.h> |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
239 #include <string.h> |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
240 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
241 #include <libircclient.h> |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
242 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
243 #include "foo.h" |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
244 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
245 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
246 Programming |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
247 ----------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
248 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
249 ### C Standard |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
250 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
251 Use C99 standard without extensions. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
252 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
253 ### Assertions |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
254 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
255 Use the `assert` macro from the assert.h header file to verify programming |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
256 errors. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
257 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
258 For example, you may use `assert` to verify that the developer access the data |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
259 between the bounds of an array: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
260 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
261 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
262 int |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
263 get(struct data *data, unsigned index) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
264 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
265 assert(index < data->length); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
266 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
267 return data->buffer[index]; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
268 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
269 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
270 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
271 The `assert` macro is not meant to check that a function succeeded, this code |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
272 must not be written that way: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
273 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
274 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
275 assert(listen(10)); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
276 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
277 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
278 ### Return |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
279 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
280 The preferred style is to return early in case of errors. That makes the code |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
281 more linear and not highly indented. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
282 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
283 This code is preferred: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
284 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
285 ```c |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
286 if (a_condition_is_not_valid) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
287 return false; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
288 if (an_other_condition) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
289 return false; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
290 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
291 start(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
292 save(); |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
293 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
294 return true; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
295 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
296 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
297 Additional rules: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
298 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
299 - Do never put parentheses between the returned value, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
300 - Do not put a else branch after a return. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
301 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
302 Shell |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
303 ===== |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
304 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
305 Write POSIX shell only with no bash, zsh or any extension. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
306 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
307 Style |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
308 ----- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
309 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
310 - Try to keep lines shorter than 80 columns |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
311 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
312 Functions |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
313 --------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
314 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
315 Don't use `function` keyword, just keep the function name. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
316 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
317 ```sh |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
318 usage() |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
319 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
320 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
321 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
322 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
323 It's usually recommended to prefix functions names with the program name to |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
324 avoid collisions with global commands. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
325 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
326 ```sh |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
327 foo_clean() |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
328 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
329 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
330 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
331 foo_process() |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
332 { |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
333 } |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
334 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
335 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
336 Options |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
337 ------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
338 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
339 For options, use `getopts` and prefer short options to long unless necessary. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
340 Also set OPTERR=0 to avoid printing errors and do it yourself for UX |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
341 consistency. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
342 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
343 ```sh |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
344 OPTERR=0 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
345 while getopts "v" arg; do |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
346 case $arg in |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
347 v) |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
348 verbose=1 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
349 ;; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
350 esac |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
351 done |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
352 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
353 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
354 Naming |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
355 ------ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
356 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
357 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
358 local variables. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
359 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
360 Markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
361 ======== |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
362 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
363 Headers |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
364 ------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
365 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
366 For 1st and 2nd level headers, use `===` and `---` delimiters and underline the |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
367 whole title. Otherwise use `###`. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
368 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
369 ```markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
370 Top level title |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
371 =============== |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
372 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
373 Sub title |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
374 --------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
375 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
376 ### Header 3 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
377 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
378 #### Header 4 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
379 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
380 ##### Header 5 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
381 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
382 ###### Header 6 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
383 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
384 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
385 Lists |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
386 ----- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
387 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
388 Use hyphens for unordered lists for consistency, do not indent top level lists, |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
389 then indent by two spaces each level |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
390 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
391 ```markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
392 - unordered list 1 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
393 - unordered list 2 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
394 - sub unordered item |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
395 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
396 1. unordered list 1 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
397 2. unordered list 2 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
398 2.1. sub unordered item |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
399 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
400 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
401 Code blocks |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
402 ----------- |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
403 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
404 You can use three backticks and the language specifier or just indent a block by |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
405 for leading spaces if you don't need syntax. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
406 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
407 ```cpp |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
408 std::cout << "hello world" << std::endl; |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
409 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
410 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
411 And without syntax: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
412 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
413 ```markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
414 This is simple code block. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
415 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
416 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
417 Tables |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
418 ------ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
419 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
420 Tables are supported and formatted as following: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
421 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
422 ```markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
423 | header 1 | header 2 | |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
424 |----------|----------| |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
425 | item 1 | item 2 | |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
426 ``` |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
427 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
428 Alerts |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
429 ------ |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
430 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
431 It's possible to prefix a paragraph by one of the following topic, it renders a |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
432 different block depending on the output format: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
433 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
434 - Note: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
435 - Warning: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
436 - Danger: |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
437 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
438 Then, if the paragraph is too long, indent the text correctly. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
439 |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
440 ```markdown |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
441 Note: this is an information block that is too long to fit between the limits so |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
442 it is split and indented. |
c188e9603faf
misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
443 ``` |