Code formatting (using clang format)

Motivation

RenderDoc uses clang-format to keep a repository with a consistent code style but also avoid as much noise in any code review process. For most things that can be automated, clang-format takes care of putting things into the repository's code style.

The formatting is checked by Travis CI for each commit and pull request so you'll know if there are any problems.

⚠️ ⚠️ Important Note ⚠️ ⚠️

Unfortunately, clang-format will change how it formats files from version to version, even if the configuration file is identical. This means that there must be a single fixed version used by everyone, otherwise different versions would format it in different ways and the formatting couldn't be automatically checked by CI.

For this reason you must use clang-format 3.8.1 specifically.

clang-format can be invoked to format a file in place like so:

clang-format -i filename.cpp

which will format the file and save a backup copy of the original file.

If you have clang-format installed and python in your path, there will be a new git command:

git clang-format

Which will check your currently modified files to see if they need to be formatted.

Automatically checking formatting on commit

Assuming you have clang-format available you can set up a git hook to automatically check that every commit complies with the clang-formatting rules. This saves a lot of time as trying to retro-actively make formatting changes and put them in each commit without adding a formatting commit at the end is kind of painful.

I've uploaded a modified version of David Martin's pre-commit format hook that will ignore 3rdparty or external source files in RenderDoc's tree that should not be formatted. You can download it here and put it in your .git/hooks folder.

With this hook active, any commit will be checked for formatting rules and you will be rejected if there's a problem. It also creates an easy-to-apply patch file that you can apply to fix up the formatting.

Formatting on save in Visual Studio

There is a LLVM-provided visual studio extension that will let you invoke clang-format on a selection or a whole document from VS. It also has an option that lets you format on save which can be quite convenient. There are similar extensions available for VS Code and other IDEs.

The only thing to be aware of is that as above clang-format 3.8.1 must be the version used. The VS extension does not let you choose the location of your clang-format.exe, it instead bundles a copy of clang-format.exe which will likely be newer.

To fix this you need to manually replace the clang-format.exe with the right version. Before doing this, make sure to uncheck "automatically update this extension" in the extensions dialog in VS otherwise VS will happily update and overwrite the file. The executable will be stored in a location similar to this:

C:\Users\<username>\AppData\Local\Microsoft\VisualStudio\14.0\Extensions\<alphanumeric string>

Where the last alphanumeric string is extension specific, but you can search for clang-format.exe under the parent folder to locate it. Note this will have to be done for each version of VS you use and install the extension into.