Visual Studio 2017 15.7 Preview 1 comes with built-in ClangFormat support for C++ developers. ClangFormat is a utility that makes it easy to style and format your code based on a set of rules that can be configured in a .clang-format or _clang-format file. This file should be present in your source code directory tree, and applies formatting conventions to all code files at the same level or in any sub-folders. It is easily shareable via source control, so you can enforce coding conventions across your whole development team.
Note that Visual Studio also supports EditorConfig, which works in a similar way. ClangFormat, however, has a much larger variety of style options than EditorConfig, including some very C++ specific rules that can be set, and it is already used by C++ developers today.
.clang-format file example
You can use multiple ClangFormat files to apply different styling rules at different locations in your codebase, if desired, by placing files in different folders. Any given code file will be styled by the ClangFormat file closest to it in the directory tree. We run the ClangFormat utility in the background to do the formatting, so you get all of ClangFormat’s features right away.
We also provide a way to enforce the built-in formatting conventions that ClangFormat ships with (LLVM, Google, Chromium, Mozilla, or WebKit) without requiring a separate ClangFormat file. This is the same as having the file there with the -style switch set to one of these conventions. This can be configured in Tools > Options.
Using the .clang-format file in the screenshot above, here is a before and after representation of a code sample when Format Document is invoked on it:
Code before the Format Document operation
Code after the Format Document operation
Some of the noticeable changes here include the maximum column width (now set to 50), and the presence of the opening curly brace on the same line as the header preceding it.
How to get started
If you already have a .clang-format or _clang-format file in your codebase, you will notice Visual Studio uses it for formatting immediately, as soon as you make an edit in your code that would trigger a formatting operation. ClangFormat also runs if you run the Format Document (Ctrl+K, Ctrl+D) or Format Selection (Ctrl + K, Ctrl + F) commands from the Edit menu or keyboard shortcuts manually in Visual Studio.
If you don’t already have a sample file to get started with, there is a handy website that features an interactive .clang-format file builder and guide to ClangFormat styling options in general. For the complete list of ClangFormat style options, visit the official documentation.
Tools > Options configuration
There are a number of configurations you can make in Tools > Options to control your ClangFormat experience. You can find them at Tools > Options > Text Editor > C/C++ > Formatting.
ClangFormat settings in Tools > Options
By default, Visual Studio will use any existing ClangFormat file in your source tree for formatting operations. To turn this off, you can uncheck Enable ClangFormat support. By default, ClangFormat will also emulate Visual Studio formatting, reacting to characters like braces ({}) and semicolons to format as you type. You can change this to have it only use ClangFormat for explicit Format Document and Format Selection commands by choosing Run ClangFormat only for manually invoked formatting commands.
The Default formatting style allows you to control your formatting experience if you do not have a .clang-format or _clang-format file in your source tree. We will always prefer that file if it exists, but if we cannot find it, we will use the formatting convention selected in that option. By default, Visual Studio is selected, meaning we do what Visual Studio usually does for formatting and do not run ClangFormat at all. However, you can also specify LLVM, Google, Chromium, Mozilla, or WebKit coding conventions as well. These function the same as having a ClangFormat file with its style property set to one of these options, with no other alterations, so in this case we’re running ClangFormat with just that setting on. So, if you’re using one of these default styles and are not planning on deviating from its rules, make the selection in Tools > Options and you’re good to go without the ClangFormat file.
Give us feedback
This feature is currently out in Preview. Please try it out and let us know if you run into any issues by reporting them via Help > Send Feedback > Report A Problem from inside the Visual Studio IDE. You can view active issues, comment on them and upvote them on Developer Community.