This file contains coding guidelines for NBEMS application source. You should follow them if you want to contribute to NBEMS. 1. General rules 1.1. Language 1.2. Version Control 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 6. Copyright header 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. Version Control -------------------- Version control is maintained using git. The remote repository for each application is at Source Forge. 2. Style, indentation and braces ================================ 2.1. Indentation ---------------- Use TABS (ASCII character #9) and _not_ SPACES. This allow everyone to set tab width to the preferred settings of 4 spaces / tab. 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(); } 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 80 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 "->", or "." object->method() 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, or be separated with an underscore. Examples: "object", "exampleClass", "anotherExampleClass" ... "example_class", "another_example_class" ... 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", "recipient_mailbox" ... 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 ".h" for header files, and ".cxx" for implementation files. If possible, files should be named exactly like the class they define. For example, class "mailboxList" should be declared in "mailboxList.h" and implemented in "mailboxList.cxx". 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. ex: #define PI_DIV_2 (M_PI / 2.0) 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. Doxygen comment are delineated with three slashes /// vice 2. 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. (notable exception is for std, "using namespace std". * 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. 6. Copyright header // ===================================================================== // // file_name.cxx // // Authors: // // Copyright (C) 2019, Dave Freese, W1HKJ // // This is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation; either version 3 of the License, or // (at your option) any later version. // // This software is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program. If not, see . // // =====================================================================