Mercurial > thymian

comparison 3rdparty/vmime/HACKING @ 0:a4671277546c tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
created the repository for the thymian project
author ferencd
date Tue, 17 Aug 2021 11:19:54 +0200
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:a4671277546c
1 This file contains coding guidelines for VMime. You should follow them
2 if you want to contribute to VMime. The rules below are not guidelines
3 or recommendations, but strict rules.
4
5
6 1. General rules
7 1.1. Language
8 1.2. Unit tests
9 1.3. Version Control
10 1.4. ChangeLog
11 1.5. Warnings
12 2. Style, indentation and braces
13 2.1. Indentation
14 2.2. Brace position
15 2.3. "switch" statement
16 2.4. Single instruction
17 2.5. Line length
18 2.6. Spaces and parentheses
19 2.7. End-of-line character
20 2.8. Short functions
21 2.9. Limit Variable Scope
22 3. Naming conventions
23 3.1. Classes
24 3.2. Variables/parameters/member variables
25 3.3. Member variables
26 3.4. Files
27 3.5. Namespaces
28 3.6. Constants
29 4. Comments
30 5. Miscellaneous
31
32
33
34 1. General rules
35 ================
36
37 1.1. Language
38 -------------
39
40 The project language is English. All comments, variable names, class names,
41 commit messages and so on, must be in English.
42
43
44 1.2. Unit tests
45 ---------------
46
47 Unit tests are very important. For each new class you write, you should also
48 write a unit test for it. If you write a new method, add a new test case in
49 the unit test of the class.
50
51 When you fix a bug, also add a new test case to ensure the bug will not
52 happen anymore.
53
54
55 1.3. Version Control
56 --------------------
57
58 Each commit MUST be done with a message ('-m' flag) that briefly describes what
59 changes have been done.
60
61 DO NOT use commit messages like -m "Updated"!
62
63
64 1.4. ChangeLog
65 --------------
66
67 ChangeLog must be updated when a major change has occured. It is not required
68 (but not forbidden) to report minor bug fixes in the ChangeLog.
69
70 Each ChangeLog entry must have an author and a date.
71
72
73 1.5. Warnings
74 -------------
75
76 The code should compile WITHOUT ANY WARNING, even those for unused parameters!
77
78
79
80 2. Style, indentation and braces
81 ================================
82
83 2.1. Indentation
84 ----------------
85
86 Use TABS (ASCII character #9) and _not_ SPACES. This allow everyone to set tab
87 width to its preferred settings (eg. 4 or 8 spaces).
88
89
90 2.2. Brace position
91 -------------------
92
93 Open braces should always be at the beginning of the line after the statement
94 that begins the block. Contents of the brace should be indented by 1 tab.
95
96 if (expr)
97 {
98 do_something();
99 do_another_thing();
100 }
101 else
102 {
103 do_something_else();
104 }
105
106
107 2.3. "switch" statement
108 -----------------------
109
110 switch (expr)
111 {
112 case 0:
113
114 something;
115 break;
116
117 case 1:
118
119 something_else;
120 break;
121
122 case 2:
123 {
124 int var = 42;
125 another_thing;
126 break;
127 }
128
129 }
130
131
132 2.4. Single instruction
133 -----------------------
134
135 Omit braces around simple single-statement body:
136
137 if (...)
138 something;
139
140 and not:
141
142 if (...)
143 {
144 something;
145 }
146
147 Except when body spans over multiple lines:
148
149 if (...)
150 {
151 something_too_long_for(
152 a_single_line);
153 }
154
155
156 2.5. Line length
157 ----------------
158
159 Each line of text should not exceed 80 characters.
160
161 Exception: if a comment line contains an example command or a literal URL
162 longer than 100 characters, that line may be longer than 100 characters
163 for ease of cut and paste.
164
165
166 2.6. Spaces and parentheses
167 ---------------------------
168
169 Put spaces around operators: =, >, <, !=, +, -, /, *, ^, %, ||, &&, &, |:
170
171 x = (a * (b + (c - d)))
172
173 Do not put spaces around parentheses.
174
175 if ((a == b) || (c == d))
176
177 Do not put spaces around "->":
178
179 object->method()
180
181 Do not put spaces inside brackets:
182
183 x = array[index] and _NOT_: x = array[ index ]
184
185 Do not use space between a function name and parenthesis. No extra spaces
186 between parameters and arguments, just after commas:
187
188 method(arg1, arg2, ...)
189
190 Do use a single space before flow control statements:
191
192 while (x == y) and _NOT_: while(x==y)
193
194
195 2.7. End-of-line character
196 --------------------------
197
198 Configure your editor to use "\n" (UNIX convention) for end-of-line sequence,
199 and not "\r\n" (Windows), nor "\n\r", nor any other combination.
200
201
202 2.8. Short functions
203 --------------------
204
205 To the extent that it is feasible, functions should be kept small and focused.
206 It is, however, recognized that long functions are sometimes appropriate, so no
207 hard limit is placed on method length. If a function exceeds 40 lines or so,
208 think about whether it can be broken up without harming the structure of the
209 program.
210
211
212 2.9. Limit Variable Scope
213 -------------------------
214
215 The scope of local variables should be kept to a minimum. By doing so, you
216 increase the readability and maintainability of your code and reduce the
217 likelihood of error. Each variable should be declared in the innermost block
218 that encloses all uses of the variable.
219
220 Local variables should be declared at the point they are first used. Nearly
221 every local variable declaration should contain an initializer. If you don't
222 yet have enough information to initialize a variable sensibly, you should
223 postpone the declaration until you do.
224
225
226
227 3. Naming conventions
228 =====================
229
230 3.1. Classes
231 ------------
232
233 Classes names are in lower-case. However, each word should start with an
234 upper-case letter.
235
236 Examples: "object", "exampleClass", "anotherExampleClass"...
237
238
239 3.2. Variables/parameters/member variables
240 ------------------------------------------
241
242 Variable names should be enough explicit so that someone reading the code can
243 instantly understand what the variable contains and is used for.
244
245 Variables names are in lower-case.
246
247 DO NOT use Hungarian notation.
248
249 Examples: "address", "recipientMailbox", ...
250
251 Avoid variable names with less than 5 characters, except for loop indices and
252 iterators.
253
254 NOTE: variable names like "it", "jt" and so on are commonly used when iterating
255 over STL containers.
256
257
258 3.3. Member variables
259 ---------------------
260
261 Use a prefix for class members: "m_" for normal class members, and "sm_" for
262 static members, if they are not public.
263
264 Examples: "m_mailboxList", "sm_instance"...
265
266
267 3.4. Files
268 ----------
269
270 Use ".hpp" for header files, and ".cpp" for implementation files. ".inc" should
271 be used for implementation files not directly compiled, but included from
272 other implementation files.
273
274 Files have to be named exactly like the class they define. For example, class
275 "mailboxList" should be declared in "mailboxList.hpp" and implemented in
276 "mailboxList.cpp".
277
278 Both header and implementation files must be placed in 'src/vmime/' directory.
279
280
281 3.5. Namespaces
282 ---------------
283
284 Namespaces are named exactly like variables.
285
286
287 3.6. Constants
288 --------------
289
290 Constants are ALL_CAPS_WITH_UNDERSCORES.
291
292
293
294 4. Comments
295 ===========
296
297 The // (two slashes) style of comment tags should be used in most situations.
298 Where ever possible, place comments above the code instead of beside it.
299
300 Comments can be placed at the end of a line when one or more spaces follow.
301 Tabs should NOT be used to indent at the end of a line:
302
303 class myClass
304 {
305 private:
306
307 int m_member1; // first member
308 int m_secondMember; // second member
309 };
310
311 Note about special comment blocks: Doxygen is used to generate documentation
312 from annotated C++ sources, so be sure to use available markings to annotate
313 the purpose of the functions/classes and the meaning of the parameters.
314
315
316 5. Miscellaneous
317 ================
318
319 * No code should be put in header files, only declarations (except for
320 templates and inline functions).
321
322 * Try to avoid public member variables. Write accessors instead (get/set).
323
324 * Do NOT use 'using namespace' (and especially not in header files). All
325 namespaces should be explicitely named.
326
327 * Use the 'get' and 'set' prefix for accessors:
328
329 Variable: m_foo
330 Get method: getFoo()
331 Set method: setFoo()
332
333 * No more than one class per file (except for inner classes).
334
335 * Put the inclusion for the class's header file as the first inclusion in
336 the implementation file.
337
338 * Put the copyright header at the top of each file.
339
340 * Write "unique inclusion #ifdef's" for header files:
341
342 #ifndef N1_N2_FILENAME_HPP_INCLUDED
343 #define N1_N2_FILENAME_HPP_INCLUDED
344
345 // ...
346
347 #endif // N1_N2_FILENAME_HPP_INCLUDED
348
349 where N1 is the top-level namespace, N2 the sub-namespace, and so on.
350 For example, class "vmime::utility::stringUtils" uses the following
351 #ifdef name: VMIME_UTILITY_STRINGUTILS_HPP_INCLUDED.
352