If you ever came to this article wondering if you should format your code, you can stop reading right now, and go check my other post on that topic.
But if you are convinced that code should be formatted, and automatically formatted, first of all welcome - this post is made for you (and for the future me if I need it ).
In this post, I am going to talk specifically about formatting C++ code, but this can also be used to format C, Java, JavaScript, Objective-C, Protobuf and C# languages. Why C++, you may ask? For no particular reason other than this is a language I use almost daily.
Enough for the introduction, letโs go in the center of the subject !
How to Format with C++ Code ?
If you Google "How to format C++ code", you will find a lot of articles and posts about tools you can use to format C++ code, which can make it difficult to choose what to do.
But there is one tool that comes back a lot of times, a tool named clang-format
, and we are going to see how to use it to format our code.
Why this one, you may wonder ?!
Well, if you build C++ code, you have probably encountered the clang compiler, which is an open-source compiler for the C family of programming languages. I wonโt go in detail on the clang
project, but as part of this project, there is the tool clang-format
which is used to format C++ code.
That means that clang-format
is actively maintained, which is really great! Moreover, clang-format
allows you to format more that C++ code! It currently allows you to format C, C++, Java, JavaScript, Objective-C, Protobuf and C# languages. So even if you donโt use C++, there is still a chance that this tool can be useful for you. In the rest of this article, each time I will talk about using clang-format
for formatting C++ code, you can think that it can do the same for those other languages.
It also allows you to customize the formatting to have the one you like for your projects, and you can integrate it inside a lot of other tools!
For all those reasons, letโs see how to actually use it.
How Does It Work ?
Good question! For those who have ever used cmake-format (a tool to format Cmake code), it works almost the same way (even if clang-format
has been created before ).
Once installed, you can use it in your terminal like that to format a file:
clang-format -i myfile.cpp
Pretty straight forward, isnโt it ?! The option -i
allows clang-format
to write the formatted version of the Cmake file in place, which means that, after you run this command, your file is now formatted.
There are a lot of options available with this tool, and I wonโt go too much in detail, but I invite you to look at them on his GitHub.
Moreover, you can create your how configuration file, that you can name .clang-format, if you want, to specify how you want some elements to render in your C++ files in a folder.
So you can format your C++ code and customize how it will be formatted! How awesome is that ?!
You Convinced Me ! How Do I Get It on My Machine, Now?
The better way to install clang-format
, is to go through a package manager. Of course, you can build it from the llvm sources, but this will take a long time and probably needs its own article. So the package manager is the way to go.
And the good news is that, whatever Operating System you are using, you can install it through a package manager:
- Linux โ
apt-get install clang-format
- Osx โ
brew install clang-format
- Windows โ
choco install llvm
Or you can install it with pip
(https://pypi.org/project/clang-format/) on whatever system you want: pip install clang-format
.
How to Automatically Format a Repository?
Now that we know how to install clang-format
, and use it to format a file, letโs see how to automatically format all the C++ files in a repository (for other language, you can use a similar method and only adapt a few characters).
If you know exactly what C++ files your project has and are sure that those will never change (no new files), you can only use the command line showing you how to use clang-format
to format them all. But, in most projects, some files will be added, moved or removed, so we need a way to format them all, without knowing their location or their name in advance.
To do so, a simple command line can do the trick by combining the command find
and clang-format
, like that:
find . \( -name '*.hpp' -o -name '*.cpp' \) -exec clang-format -i {} \;
This command will look through all the folders and sub-folders from your current position, and look for the files with the extension .hpp or .cpp files. Then it will place all those files in place of the {}
and run the command clang-format -i
with all the files. If you are using other extension for the files, you can add or remove them until all the files you want to format are given to the command line!
And voilร , you have it! One line, you can format them all.
And There Is More !
The one line command to format all the C++ files is good, but, I must say that this is not a line easy to remember. This issue can prevent people to use it because they donโt want to go through the documentation to find it again to paste it in their terminal. And we canโt be mad at them for that, if they can, people will always resist change, so if you have such line to learn without being convinced of the benefits of formatting, you wonโt learn it.
So what to do? We have only one line? Can we make it simpler?
And yes, we can !
To do so, you can create a Makefile, on top level of your project repository, so that you will have an alias for this complicated line. This Makefile
will be as simple as that:
<code class="language-Makefile">format:
set -f
find . \( -name '*.hpp' -o -name '*.cpp' \) -exec clang-format -i {} \;
set +f
And now, all people will have to do is to run make format
, and all the formatting will occur without them having to learn a complicated line.
This is actually more powerful than that! If for some reason, you have to change the tool you use for formatting C++ files, all you have to do, is to modify the Makefile
, and your coworkers wonโt even be bothered by it, since the command make format
will still be the thing they will have to do ! Moreover, if you want, you can also add other formatting tools for other language in the Makefile
so that the command make format
formats actually all your source files, whatever their languages !!!
I also have to mention that, to help to integrate it to your workflow, clang-format
can also be include in a lot of other tools, such as Vim, Emacs, BBEdit, CLion, Visual Studio, and probably a lot more if you search for them.
Letโs Force Format by Default !
Now, we have an easy-to-remember command that allows us to format our C++ code. Everybody is happy, and uses it. Everybody, well actually no, there is this one time you forgot, and the code has been integrated to the project, and now, everybody has formatting conflicts. Or that time when the new intern didnโt know he (or she) that this command existed. Or those coworkers that want to use it, but still forgets, since they donโt have the habit yet.
For all these reasons, and maybe more, you should go for the formatting by default. But what do I mean by that ? Itโs simple, you should make it impossible, or at least, very difficult for anyone to not format his code, and have this not-formatted code be integrated in production, or even reach code reviews !
How do we do that ? Well, there are actually two things you can do.
Pre-commit Hook
If you are using git
(and I hope you do version your code), you can create what is called a pre-commit hook. This is a script that is going to be executed before each of your commits, which is perfect for formatting !
Indeed, if, before any of your commits, you can automatically format your code, then, you wonโt ever forget it, or even have to think about formatting again! This is how you gain back some time to do some more important stuff: automation !!
You can find here, an example of pre-commit hook that may help you to have your own.
CI Check
Another way to force the formatting of the files on your repository, is to create a check on a CI/CD system such as Travis.
If you are not familiar with the concept of Continuous Integration, I encourage you to look at it, it will truly benefit you, and your team. For those who know what a CI/CD system such as Travis is, letโs continue.
But how can we test that the files of our repository are well formatted? Pretty easily actually, all we have to do is to implement these three steps:
- Get
clang-format
on the system, if it is not already installed - Run the format command
make format
- Check that the formatting didnโt change any files
If we can implement all of them, we win.
Actually, we already have 2 of them ! We know that we can install clang-format
using pip
! This is a first win. And running the command make format
is as simple as executing any other command on a CI/CD system.
So all we have left, is to check if one file has changed after the formatting, which will mean that the person did not format his code before the commit or the push on the CI. And there is a command line for that too.
git diff --exit-code
This command will check the difference for the files in your repository, and will return 0
(= success) if no change is detected, and something else (=failure) if a file has changed.
And voilร , we have our 3 steps.
To help a bit more, you will find below this line, the content of a GitHub Action which does exactly that ! Since GitHub Actions is now available, I think that it might be easier for anyone to integrate it that way.
name: C/C++ CI
on: [push]
jobs:
build:
runs-on: windows-2016
steps:
- uses: actions/checkout@v1
- name: Running cpp formatting
run: make format
- name: Checking formatting
run: git diff --exit-code
No need to install clang-format
since it is already installed by default on the system provided by GitHub Action. \o/
Conclusion
In conclusion, I will say that writing this article was pretty fun. I sincerely hope that you had as much fun reading it as I had writing it , and that it will help you to have a better workflow (at least for the formatting part) in your code. I will write some other articles to help you and myself to format files of other languages. They will be available in the coming weeks.
And until then, have fun learning, growing, and have a wonderful time.