Coding standards

It is highly recommended to use a single coding style for the whole project source code. Exceptions are allowed for external libraries used in the project, but it is generally advisable all contributors to use this style.

Tab Size

First of all, we use spaces. Tabs are four-character width. That is, no 8-space tabs, no 2-space tabs. Four. Unfortunately there's no such thing as 'standard tab width', and 4-space indenting looks best from our point of view, besides MSVC' editor has this setting by default.

Line length

Then, please use 80-character wide lines. If your line is way longer than that, please split it. If it's just a little longer, so be it. The continuation text, if you're splitting text inside the brackets, should be indented to the position after the opening bracket:

printf("This is a example of how we split lines longer than %d characters\n"
       "into several so that they won't exceed this limit.\n",
       max_sourcecode_width);

If you have long strings, you can split them as shown above, just remember that C/C++ compilers will glue together several strings that come without any special characters between them into one.

Brackets

Now we use symmetric bracket placement, closing bracket under the opening bracket:

if (something)
{
    ...;
}
else
{
    ...;
}

switch (x)
{
    case 1:
        printf("X is one!\n");
        break;
    case 2:
    {
        printf("X is two!\n");
        break;
    }
}

for (int i = 1; i < 3; ++i)
{
    printf("I is %i!\n", i);
}

Every bracketed block moves its contents by one tab to right. Labels (but not case selectors or 'public:/private:/protected' C++ keywords) are placed at the leftmost indention position for the current block, that is, in the same position where enclosing brackets are.

Also please don't use brackets around a single statement because it clutters the code with unneeded stuff; use brackets only when using non-obvious constructs, like:

if (...)
{
    if (...)
        ...;
}
else
    ...;

Also, please place one space before opening parenthesis. Before, but not after (the if ( blah ) style is a no-no!).

Class declaration and constructors

Here is an example:

class Class : public Parent
{
    public:
        Class() : Parent(0),
            m_field(1)
        {
            func();
        }

       void func() {}

    private:
        int m_field;
};

Please follow the following rules for classes:

space before and after : in class parents list and constructor body
next line and indent for class field initialization list
indent for public:/private:/protected: section with additional indent for section content
empty or short function body can be at same line with declaration in in-class definition case

Code documentation with Doxygen

Now, please use DoxyGen-type comments. This is a bit similar to JavaDoc comments and to other automatic code documentation generation tools. One-line documentation should be placed in /// (three slashes) comments if the comment is above the function/member, if you want the comment on the same line you should use ///< instead, multi-line comments should be put in a /** ... */ block (slash-two-stars).

Here's a example that shows most useful keywords that you can use in a comment block:

/**
* This function does something very useful. If used with care, this function
* has the potential to make your programs really really useful.
*
* \arg \c x
*   The x argument specifies a integer that is transformed into something useful.
* \arg \c y
*   This argument, if not NULL, is a pointer to a free memory area where this
*   function will put something really really useful.
* \return
*   A useful value, or NULL if error.
*
* Here is a example that you can paste into your code so that it saves you a
* lot of typing:
*
* \verb atim  (Remove the space)
* for (int x = 0; x < 100; ++x)
*     printf("DoSomethingUseful%d = %s\n", i,
*             DoSomethingUseful(i, &ScratchPad));
* \endve rbatim (Remove the space)
*
* Paragraphs are split from each other by inserting a empty line. Also some HTML
* tags are supported, like <ol> [<li>...] </ol> and <ul> [<li>...] </ul> for
* ordered (numbered) and unordered (dotted) lists respectively.
*/
char *DoSomethingUseful(int x, void *y);

/// This is a one-line comment
void Something();

Use normal comments like // and /* ... */ only if you want to make a comment that should not go into the automatically annotated code (like: /* shit ... this does not work */).

4.8 KiB Raw Permalink Blame History