C Style

C / C++ Style & Standards

C and C++ don't have any "standard" styles, so we will define our own, in keeping with the spirit of PEP-8 for consistency.

Files

• File names should be in lower_case_with_underscores. C and C++ sources should be accompanied by a header file with the same name:

$ ls
example.c
example.h
cpp_example.cpp
cpp_example.h

• Each .c or .cpp file should be accompanied by a .h file.
• Each .h file should contain an include guard; the name of the define should be the file name in all caps with underscores suffixed by _H:

/**
 * File docstring
 */

#ifndef FILE_NAME_H
#define FILE_NAME_H

// Includes inside the include guard, in case an included file doesn't have
// its own include guard
#include "example_file.h"
#include <example_lib.h>

// Definitions go here

#endif

Line limits

• Files must be shorter than 300 lines, except for configuration files. If possible, keep files shorter than 250 lines.
• If possible, keep functions under 50 lines.
• Maximum of 79 characters per line

Indentation

• Four spaces per indentation level
• Continuation lines and hanging indents aligned with the opening delimiter or on a new line with an additional level of indentation

Blank spaces

• Two empty lines between top-level function, class, enum, typedef, and struct definitions
• One empty line between class methods
• At most one consecutive blank line within functions and methods to separate logical sections

Naming

• Classes in UpperCamelCase
• Constants, #define, and types in ALL_CAPS_WITH_UNDERSCORES
• Functions and variables in lowerCamelCase
• Structs in lower_case_with_underscores_t (trailing _t)

Curly Braces

• If statements should always be followed by a curly brace. Even though this is valid C, this is VERY BAD:

if(condition)
    printf("If you write code like this, please stop.");

• Curly braces should get their own line, except when the contents of the delimiter are very short. In any case, try to follow the format of previous lines:

int good_example(int input)
{
    int super_long_variable_name;

    // These two if statements are allowed to be on one line since the
    // contents are very short.
    if(input > 5) { return 0; };
    if(input % 3 == 0) { input -= 1; };

    super_long_variable_name = input;

    // This if statement definitely will not fit on one line.
    if(super_long_variable_name * 3 + super_long_variable_name % 5 == 1)
    {
        return super_long_variable_name * super_long_variable_name;
    }
    // This could be on a single line, but is written out in order to be
    // consistent with the previous statement.
    else
    {
        return 2;
    }
}

Comments

• Comments without special meaning (function headers, member documentation, etc) should use two slashes. /* comment */ comments should be reserved for special comments.
• Trailing comments should be used sparingly. Trailing comments should be 4-space aligned when possible, and at least two spaces to the right of code on the same line.

Documentation

C / C++ functions and classes should be documented using doxygen directives.

As long as all of the information is there, it's not a big deal if the documentation doesn't fit perfectly with the prescribed format (although it is annoying, since someone will have to go through and fix it).

Specifically, we will be using the "JavaDoc" style, with JAVADOC_AUTOBRIEF = YES.

/**
 * Brief description.
 * This is the long description. Notice the two asterisks at the top of the
 * comment block, instead of just one.
 */
class ExampleClass
{
    public:
        /** An enum type.
         *  The documentation block cannot be put after the enum!
         */
        enum EnumType
        {
            int EVal1,      /**< enum value 1 */
            int EVal2       /**< enum value 2 */
        };
        void member();      /**< a member function. */

    protected:
        int value;          /**< an integer value */
};

/**
 * This is what a function looks like.
 * Long description of the function on this line.
 *
 * @param input input value
 * @param buffer output buffer
 * @return 1 if successful, 0 if unsuccessful.
 */
int exampleFunction(int input, int buffer[5]);

Dividers

Dividers, if used at all, will most likely be found in large header files with a lot of #defines, enums, and typedefs. Since each .c file should have

Large divider:

// ----------------------------------------------------------------------------
//
//                              Divider Caption
//
// ----------------------------------------------------------------------------

Small divider:

// -- Divider Caption ---------------------------------------------------------