The Benefits of Code Formatting
Enforcing a consistent code style for a code base greatly improves the readability and reduces the potential for merge conflicts when multiple developers work on the same project. While most companies have style guides, the code style is often not enforced automatically and developers must write their code to match the requirements.
The clang-format toolset is our go-to option for automatic code formatting because of the easy integration into Qt Creator and its configurability.
Styles
The clang-format tool supports several built-in style presets. If the style is set to file, custom styles are read from a file named .clang-format or _clang-format which must be located in the same directory or a parent directory of the source code location. The closest configuration file always overrides previous files, so subtrees of the project directory structure can use different code styles.
If the file style is used and no file is available, the default behavior of clang-format is to apply a fallback style. To prevent this, the fallback style option must be set to none.
For new projects without style requirements provided by the customer, we usually recommend the Qt style file from the qt5 repository.
Excluding Files and Directories
To exclude files, directories or entire subtrees from automatic formatting, clang-format reads a file named .clang-format-ignore which follows the same override logic as .clang-format.
This comes in handy if out project embeds source code from a git submodule without a .clang-format file where automatic formatting might mess up an entire file after one small change. By adding the directory to a .clang-format-ignore file residing in the repository under our control, we can prevent automatic formatting from being performed without making changes to the submodule repository and without placing untracked files in its directory.
Due to a bug in clang-format which was fixed in October 2024, the way most auto formatting extensions for IDEs (including Qt Creator) call it ignored exclusions from the .clang-format-ignore file. The fix is already included in the current clang-format 20 releases.
If only versions up to clang-format 19 can be used during development, putting a .clang-format file containing the text DisableFormat: true into the directory to exclude is a viable workaround.
Integration into Qt Creator
The features of clang-format are available in Qt Creator by enabling the Beautifier plugin. This adds a new entry named Beautifier to the preferences dialog.
In the General tab, the Tool option must be set to ClangFormat. We also recommend enabling the Automatic Formatting on File Save checkbox to fully automate the formatting process.
The ClangFormat tab contains a few more settings we need to adapt to our development setup and project requirements.
The ClangFormat command option must be set to the path of the clang-format executable. Depending on the operating system, clang-format is available in the official repositories (most Linux distributions) or must be downloaded and installed (Windows).
The predefined style should be set to one of the preset styles or the file style. We recommend setting the fallback style to none in order to avoid unpleasant surprises when opening unrelated projects and files using the same Qt Creator configuration.
While the Beautifier plugin also provides a way to input the custom style options using the Use customized style radio button, we always recommend the file style. This allows checking the code style file(s) into our repository so they can be used by fellow developers without complex setup steps, no matter which development setup they use.
Conclusion
With a few clicks, we have enabled automatic code formatting in Qt Creator and never have to think about braces placement, white spaces and breaking long lines ever again. If a file containing changes is saved, it will be formatted automatically according to the options defined in our .clang-format file.
By adding the configuration files to the repository, the code style becomes part of the project and can be applied by most IDEs or by invoking clang-format from the command line.
The steps described above still require some cooperation from all developers. In order to really enforce the code style and to make sure that all developers contributing to the project apply clang-format, it could be a good idea to add a check to the CI pipeline which blocks merge requests if the committed code does not follow the rules of the .clang-format file.
Sorry, comments are disabled on this post.