File: HACKING

package info (click to toggle)
libvmime 0.9.2-6
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 4,552 kB
  • sloc: cpp: 55,419; ansic: 822; makefile: 88; sh: 8
file content (342 lines) | stat: -rw-r--r-- 8,084 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
This file contains coding guidelines for VMime. You should follow them
if you want to contribute to VMime. The rules below are not guidelines
or recommendations, but strict rules.


1. General rules
     1.1. Language
     1.2. Unit tests
     1.3. Version Control
     1.4. Warnings
2. Style, indentation and braces
     2.1. Indentation
     2.2. Brace position
     2.3. "switch" statement
     2.4. Single instruction
     2.5. Line length
     2.6. Spaces and parentheses
     2.7. End-of-line character
     2.8. Short functions
     2.9. Limit Variable Scope
3. Naming conventions
     3.1. Classes
     3.2. Variables/parameters/member variables
     3.3. Member variables
     3.4. Files
     3.5. Namespaces
     3.6. Constants
4. Comments
5. Miscellaneous



1. General rules
================

1.1. Language
-------------

The project language is English. All comments, variable names, class names,
commit messages and so on, must be in English.


1.2. Unit tests
---------------

Unit tests are very important. For each new class you write, you should also
write a unit test for it. If you write a new method, add a new test case in
the unit test of the class.

When you fix a bug, also add a new test case to ensure the bug will not
happen anymore.


1.3. Version Control
--------------------

Each commit MUST be done with a message ('-m' flag) that briefly describes what
changes have been done.

DO NOT use commit messages like -m "Updated"!


1.4. Warnings
-------------

The code should compile WITHOUT ANY WARNING, even those for unused parameters!



2. Style, indentation and braces
================================

2.1. Indentation
----------------

Use TABS (ASCII character #9) and _not_ SPACES. This allow everyone to set tab
width to its preferred settings (eg. 4 or 8 spaces).


2.2. Brace position
-------------------

Open braces should always be at the beginning of the line after the statement
that begins the block. Contents of the brace should be indented by 1 tab.

   if (expr)
   {
         do_something();
         do_another_thing();
   }
   else
   {
         do_something_else();
   }


2.3. "switch" statement
-----------------------

   switch (expr)
   {
   case 0:

        something;
        break;

   case 1:

        something_else;
        break;

   case 2:
   {
        int var = 42;
        another_thing;
        break;
   }

   }


2.4. Single instruction
-----------------------

Omit braces around simple single-statement body:

   if (...)
      something;

and not:

   if (...)
   {
      something;
   }

Except when body spans over multiple lines:

   if (...)
   {
      something_too_long_for(
         a_single_line);
   }


2.5. Line length
----------------

Each line of text should not exceed 80 characters.

Exception: if a comment line contains an example command or a literal URL
longer than 100 characters, that line may be longer than 100 characters
for ease of cut and paste.


2.6. Spaces and parentheses
---------------------------

Put spaces around operators: =, >, <, !=, +, -, /, *, ^, %, ||, &&, &, |:

    x = (a * (b + (c - d)))

Do not put spaces around parentheses.

    if ((a == b) || (c == d))

Do not put spaces around "->":

    object->method()

Do not put spaces inside brackets:

    x = array[index]     and _NOT_:    x = array[ index ]

Do not use space between a function name and parenthesis. No extra spaces
between parameters and arguments, just after commas:

    method(arg1, arg2, ...)

Do use a single space before flow control statements:

    while (x == y)     and _NOT_:    while(x==y)


2.7. End-of-line character
--------------------------

Configure your editor to use "\n" (UNIX convention) for end-of-line sequence,
and not "\r\n" (Windows), nor "\n\r", nor any other combination.


2.8. Short functions
--------------------

To the extent that it is feasible, functions should be kept small and focused.
It is, however, recognized that long functions are sometimes appropriate, so no
hard limit is placed on method length. If a function exceeds 40 lines or so,
think about whether it can be broken up without harming the structure of the
program.


2.9. Limit Variable Scope
-------------------------

The scope of local variables should be kept to a minimum. By doing so, you
increase the readability and maintainability of your code and reduce the
likelihood of error. Each variable should be declared in the innermost block
that encloses all uses of the variable.

Local variables should be declared at the point they are first used. Nearly
every local variable declaration should contain an initializer. If you don't
yet have enough information to initialize a variable sensibly, you should
postpone the declaration until you do.



3. Naming conventions
=====================

3.1. Classes
------------

Classes names are in lower-case. However, each word should start with an
upper-case letter.

Examples: "object", "exampleClass", "anotherExampleClass"...


3.2. Variables/parameters/member variables
------------------------------------------

Variable names should be enough explicit so that someone reading the code can
instantly understand what the variable contains and is used for.

Variables names are in lower-case.

DO NOT use Hungarian notation.

Examples: "address", "recipientMailbox", ...

Avoid variable names with less than 5 characters, except for loop indices and
iterators.

NOTE: variable names like "it", "jt" and so on are commonly used when iterating
over STL containers.


3.3. Member variables
---------------------

Use a prefix for class members: "m_" for normal class members, and "sm_" for
static members, if they are not public.

Examples: "m_mailboxList", "sm_instance"...


3.4. Files
----------

Use ".hpp" for header files, and ".cpp" for implementation files. ".inc" should
be used for implementation files not directly compiled, but included from
other implementation files.

Files have to be named exactly like the class they define. For example, class
"mailboxList" should be declared in "mailboxList.hpp" and implemented in
"mailboxList.cpp".

Both header and implementation files must be placed in 'src/vmime/' directory.


3.5. Namespaces
---------------

Namespaces are named exactly like variables.


3.6. Constants
--------------

Constants are ALL_CAPS_WITH_UNDERSCORES.



4. Comments
===========

The // (two slashes) style of comment tags should be used in most situations.
Where ever possible, place comments above the code instead of beside it.

Comments can be placed at the end of a line when one or more spaces follow.
Tabs should NOT be used to indent at the end of a line:

   class myClass
   {
   private:

       int m_member1;         // first member
       int m_secondMember;    // second member
   };

Note about special comment blocks: Doxygen is used to generate documentation
from annotated C++ sources, so be sure to use available markings to annotate
the purpose of the functions/classes and the meaning of the parameters.


5. Miscellaneous
================

* No code should be put in header files, only declarations (except for
  templates and inline functions).

* Try to avoid public member variables. Write accessors instead (get/set).

* Do NOT use 'using namespace' (and especially not in header files). All
  namespaces should be explicitely named.

* Use the 'get' and 'set' prefix for accessors:

     Variable:    m_foo
     Get method:  getFoo()
     Set method:  setFoo()

* No more than one class per file (except for inner classes).

* Put the inclusion for the class's header file as the first inclusion in
  the implementation file.

* Put the copyright header at the top of each file.

* Write "unique inclusion #ifdef's" for header files:

     #ifndef N1_N2_FILENAME_HPP_INCLUDED
     #define N1_N2_FILENAME_HPP_INCLUDED

     // ...

     #endif // N1_N2_FILENAME_HPP_INCLUDED

  where N1 is the top-level namespace, N2 the sub-namespace, and so on.
  For example, class "vmime::utility::stringUtils" uses the following
  #ifdef name: VMIME_UTILITY_STRINGUTILS_HPP_INCLUDED.