Skip to content

026_tool.cpp_code_formatting.md

Latest commit

 

History

History
51 lines (35 loc) · 2.74 KB

026_tool.cpp_code_formatting.md

File metadata and controls

51 lines (35 loc) · 2.74 KB

Apply C/C++ code formatting

Goals

Keep code readable by applying consistent code styles

Description

To ensure readable code it's important to apply consistent coding style guidelines. Use tools to help your team to stay consistent and not waste time while coding and during reviews to fix tedious formatting mistakes.

Environment

C/C++

Platform

All

Implementation effort

Minimal

Applicability

Applicable to code that has just been written by yourself. Reformatting code without careful consideration makes tracking changes more difficult, and disrupt the work of others who may be using the same code.

Generally, "format-on-save" should only be turned on if all members of project adhere to coding style. Code style adaptions (e.g. in an existing code base) should ONLY be done on a commit-basis, "format-on-save" should not be used in these cases. If you want to adapt the code base or single files to a new or changed format use style-change-only-commits without changing any logic. This will make tracking changes in your version control system easier.

Caveats

Formatting tools do not always format code as you would like. Especially line breaks are common issues. You might use // clang-format off and // clang-format on comments around a line or section to disable clang-format sporadically to manually format the code.

See also

Implementation hints

At project start, decide which coding style to use. Ask the customer if there are in-house styles which should be implemented. If the customer doesn't care we will use the official Qt C++ code style.

It is good practice to put a (custom) .clang-format file into your repository, so developers are using the same configuration.

You may want to adapt your CI-checks to involve a formatting check in order to catch formatting errors automatically.

Use your IDE to apply coding styles while writing (in QtCreator: Options > C++ > Code Style). When using clang-format, developers should choose the same version, to avoid conflicting formatting, caused by a different program version.

Use IDE to 'convert' whole files