Automatic Code Formatting and ClangFormat

One of the last things we want to look towards the end of this course is the topic of code style.

We've already seen that the compiler doesn't necessarily care about how our code is written. From the compiler's point of view, all of the following are equivalent:

1int Character::GetHealth() const
2{
3  return Health;
4}
5

1int Character::GetHealth() const {
2  return Health;
3}
4

1int Character::GetHealth() const { return Health; }
2

1int
2         Character::GetHealth()
3const		{
4return Health;
5	}
6

However, humans need to read our code too. We generally want to have code laid out in a way that is consistant, and easy to read.

When working for a company, or in a project shared by multiple developers, we tend to agree to all use the same style. This is something generally called a Style Guide.

Automatic Code Formatting

Experienced developers typically do not do format their code manually. We automate this process.

It's likely you've already seen this in action - your editor has probably been indenting and laying out code for you.

Editors have settings that allow us to control that process, and have it lay out the code in a way we specify.

However, it's more common to create a configuration file that does this for us. Configuration files are often more powerful than an editor's built in settings.

They're also easier to share across the members of our team, and some formats work across different IDEs. So, everyone's code can follow the same pattern.

There are many options for how to create these files, but a common choice is ClangFormat.

ClangFormat

To use ClangFormat, we just need to create a file called .clang-format (note the initial .) in the root directory of our project.

In Visual Studio, we can create this by Right-Clicking on our project name in the Solution Explorer, and going to Add > New Item. In the Formatting section on the right, we should see the ClangFormat template. We need to leave the name as the default (.clang-format) and add it to our project.

Google's style guide is automatically available within clang-format. We can use by updating our .clang-format file to be this single line:

1BasedOnStyle: Google
2

Aside from Google, other starting points are available. You may want to try Mozilla, LLVM and Microsoft here instead.

From there, we can add additional rules to update or override our imported settings. For example, we could set our indent size and maximum line length using the following:

1BasedOnStyle: Google
2
3IndentWidth: 2
4ColumnLimit: 60
5

All the rules we can use to set up clang-format are available in the documentation.

Many .clang-format files are available online for us to copy, update and play around with until we find something that works for us.

Those interesting in applying the style of Unreal Engine can use the clang-format file made available by this this community member.