Coding Conventions

Classes

Class names should be written in PascalCase like so:

class MyClass {};

Class-private or protected member variables should be prefixed with m_, using camelCase:

class MyClass {
protected:
    int m_someValue;
    std::string m_anotherValue;
};

Note that to avoid verbosity the above is not followed for structures with public data members, like vector3.

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

class MyClass {
public:
    void MyFunction() {}
};

Global variables

Global variables must be prefixed with g_, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static scope should be prefixed with s_, and similarly use camelCase:

static int s_classScopeVariable;
// ...
static int s_fileScopeVariable;

Code Formatting

The Pioneer C++ codebase has an enforced common coding style, managed by running the clang-format tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a git hook. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

Diagnosing Formatting Issues

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in diff(1) format.

Installing a Git Hook

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code before you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's hooks/ directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook

Once you have installed the hook, simply run git commit as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run git commit --no-verify.

Applying The Format Changes

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

$ ./autoformat

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.