diff options
Diffstat (limited to 'vmime-master/HACKING')
-rw-r--r-- | vmime-master/HACKING | 360 |
1 files changed, 360 insertions, 0 deletions
diff --git a/vmime-master/HACKING b/vmime-master/HACKING new file mode 100644 index 0000000..a1cf21c --- /dev/null +++ b/vmime-master/HACKING @@ -0,0 +1,360 @@ +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 end of the line of 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(); + } + +In a function, the opening brace must always be followed by an empty line: + + void header::appendField(const shared_ptr <headerField>& field) { + + m_fields.push_back(field); + } + +A function with few arguments: + + bool header::hasField(const string& fieldName) const { + + ... + } + +A function with more arguments: + + void header::parseImpl( + const parsingContext& ctx, + const string& buffer, + const size_t position, + const size_t end, + size_t* newPosition + ) { + + ... + } + + +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 +----------------------- + +Don't omit braces around simple single-statement body: + + if (...) { + something; + } + +and not: + + if (...) + something; + + +2.5. Line length +---------------- + +If possible, each line of text should not exceed 100 characters, except if +manual line wrapping breaks code clarity. + +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 #include for the class's header file first 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. + |