Reducing the effort required to keep code style consistent is important, because doing so helps readability, and the task is not very interesting. clang-format is a great tool for re-styling entire C++ files, or even small sections, automatically. It provides a wide array of configuration options, listed here, and some default configurations for style guides from LLVM, Google, etc.

The OpenRW project provides a clang-format configuration that applies a reasonable style to the codebase. While using it I’ve found a few useful things that improve my workflow, and have some ideas of what could be improved.

Trailing comma in list initialisation

Leaving a trailing comma in a C++ list initialisation is a useful pattern for lists that are likely to change. As you don’t need to change the previous entry if you add another element.

clang-format takes this into account by breaking each element onto its own line if there is a trailing comma after the last item. This greatly improves readability in larger lists and simplifies diffs when changes are made.

std::vector<mytype_t> kMyElements{
    {
        "foo",
        {
            "bar", "baz",
        },
    },
    {"one", {"two", "three"}},
};

The 2nd element has been squashed down to one line, despite being almost exactly the same number of symbols as the first. This is great for nested structures and long lists that are difficult to read when not expanded.

QtCreator integration

QtCreator is my daily driver, and so it would be useful to have a hotkey for applying clang-format to a block of code. The QtCreator developers seem to feel the same way, since it comes with a plugin called Beautifier. This can apply a few different code styling tools to open documents, including clang-format.

To enable it, just click Help > About Plugins and tick Beautifier, then restart QtCreator. You can then run clang-format from the Tools menu. Unfortunatley you can’t select a clang format configuration file to use, but you can copy the configuration into the Tools > Options > Beautifier > clang-format screen.

I find it’s useful to have a keyboard shortcut to continually re-format the code I’m working on. To set up a hotkey for this, click on the Environment > Keyboard tab, then search for clangformat. I typically use Ctrl+? as it doesn’t conflict with anything else.

Enforcing style in pull requests

As the number of contributors to OpenRW increases, reducing the burden on those reviewing pull requests is critical. Nit picking about style is something nobody should expend effort over, so I would like to have clang-format be part of the continious integration process.

I’e not yet implemented this in the OpenRW project but I can imagine a system that I would be reasonable to use. Before the code is built on travis, a script should run that applies clang-format to the lines changed between the master and the branch commits. If this script produces any output, then the build will be marked as failed and the user should get a useful diagnostic of what they need to change to fix the style.