Coding conventions

From MailWasher Server

While there are a couple of older modules that do not properly follow the coding conventions, we want to stick to it firmly in any new units, in all FCL modules, and in the MPD and 'common' directories.

Summary of formatting conventions

• 4-space tabs, use tab characters.
• Braces to open and close blocks and control structures on new lines. Braces on the same indentation as the control statement/scope.
• In switch statements, indent once for case label, another for code under case - if using braces for the 'case' term, they go at the same level as the case term.
• Spaces around keywords. Spaces after the sections of a for statement. No spaces inside parentheses. Spaces around binary/ternary operators, unless grouping for clarity.

Summary of naming conventions

• Class names: PascalCase. Acronyms all-capitalised (HTMLParser). Includes any non-built-in exceptions and non-primitive typedefs.
• Field and variable names: camelCase (htmlParser, someHTMLParser).
• Constants: JAVA_CONSTANT_CASE.
• Enumeration values: lower_case_underscored.

Code documentation

Needless to say, all developers are expected to document their work. Aside from any comments in the actual code itself, all public, most protected, and many private classes, constructors, methods, and fields should have Javadoc-style documentation comments (which can be converted to HTML using the free and cross-platform doxygen).

An example

The formatting conventions are best shown by example:

/**
 * This is an example class for the coding conventions guide.
 */
class SomeClass:
	public ISomething,
	public ISomethingElse
{
public:
    /**
     * This method is just an example of coding conventions.
     *
     * Write documentation for all public class elements!
     *
     * @param count The number of times to print the string.  Must be non-negative.
     * @param str The string to print.
     * @throws invalid_argument if <tt>someArgument</tt> is negative.
     */
    int someFunction(int count, std::string str);

public:
    /**
     * We use java-style constant naming - all capitals, with underscores.
     */
    int SOME_CONSTANT = 1;
};


int SomeClass::someFunction(int count, string str)
{
    switch (count)
    {
        case 0:
            break;

        case 1:
            cout << str << endl;
            break;

        default:
            if (count > 0)
            {
                for (int i = 0; i < count; i++)
                {
                    cout << i << ": " << anotherParameter << endl;
                }
            }
            else
            {
                throw invalid_argument("supplied argument is negative");
            }
    }
}