Coding Conventions

Classes

Class names in camel case starting with upper case like so:

class MyClass {};

Class member variables prefixed with m_, camel case starting with lower case:

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

Note that to avoid verbosity the above is not followed for classes that are used more like structs, like vector3.

Class functions should be camel case starting with upper case:

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

Global variables

Global variables must be prefixed with g_, and use camel case starting with lower case:

int g_screenWidth;

Variables with static scope should be prefixed with s_:

static int s_someGlobalForJustThisFile;

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/pre-commit-hook.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 run the below command, replacing FILE... with the paths to the files that need to be fixed.

~/.../pioneer $ clang-format -style=file -i FILE...

This will direct clang-format to overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, but rather determine which changes will be made first (by running git commit or scripts/pre-commit-hook.sh to trigger the validation hook).

A script to automatically apply the results of the clang-format validation pass is planned, but not currently written. Once it is created, applying the code format changes will be as simple as running a single script from the main pioneer directory, and confirming the changes you want to apply.