From 6cad2eb793c5ff923a4b1ea52573fcd1ca07d482 Mon Sep 17 00:00:00 2001 From: Jonas Kalinka Date: Mon, 19 Feb 2024 11:18:39 +0100 Subject: [PATCH 1/3] added cpp code formatting --- 026_tool.cpp_code_formatting.md | 51 +++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 026_tool.cpp_code_formatting.md diff --git a/026_tool.cpp_code_formatting.md b/026_tool.cpp_code_formatting.md new file mode 100644 index 0000000..839c272 --- /dev/null +++ b/026_tool.cpp_code_formatting.md @@ -0,0 +1,51 @@ +# Tool 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. + +Additional considerations: +- Put a (custom) clang-format file into your repository, so developers are using the same configuration. +- Adapt your CI-checks to involve a formatting check in order to catch formatting errors automatically. + +## Caveats +Formatting tools are 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 + +- [QML code formatting](https://toolbox.basyskom.com/29) +- [Continuous Integration keeps your project healthy](https://toolbox.basyskom.com/3) + +## 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](https://wiki.qt.io/Qt_Coding_Style). + +Use IDE to apply coding styles while writing (in QtCreator: `Options > C++ > Code Style`). + +Use IDE to 'convert' whole files + +- QtCreator: enable 'Beautifier' plugin and configure it appropriately. Requires `clang-format`, `astyle` or `uncrustify` to be installed in the system +- Clang format + - Linux: `apt install clang-format` + - Windows: install from http://llvm.org/builds/ +- Artistic Style + - Linux: `apt install astyle` + - Windows: install from https://sourceforge.net/projects/astyle/files/ +- Uncrustify + - Linux: `apt install uncrustify` + - Windows: install from https://sourceforge.net/projects/uncrustify/files/ From 11bf615fee552ea735618895b95fe2c642b1451e Mon Sep 17 00:00:00 2001 From: Jonas Kalinka Date: Mon, 19 Feb 2024 18:01:53 +0100 Subject: [PATCH 2/3] removed 'tool' from title --- 026_tool.cpp_code_formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/026_tool.cpp_code_formatting.md b/026_tool.cpp_code_formatting.md index 839c272..293df3f 100644 --- a/026_tool.cpp_code_formatting.md +++ b/026_tool.cpp_code_formatting.md @@ -1,4 +1,4 @@ -# Tool Apply C/C++ code formatting +# Apply C/C++ code formatting ## Goals Keep code readable by applying consistent code styles From cf70f67551efec056aea95f538a954dd188376c7 Mon Sep 17 00:00:00 2001 From: Jonas Kalinka Date: Thu, 22 Feb 2024 14:41:18 +0100 Subject: [PATCH 3/3] added hint on clang-format version and some minor fixes --- 026_tool.cpp_code_formatting.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/026_tool.cpp_code_formatting.md b/026_tool.cpp_code_formatting.md index 293df3f..6614446 100644 --- a/026_tool.cpp_code_formatting.md +++ b/026_tool.cpp_code_formatting.md @@ -20,12 +20,8 @@ Applicable to code that has just been written by yourself. Reformatting code wit 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. -Additional considerations: -- Put a (custom) clang-format file into your repository, so developers are using the same configuration. -- Adapt your CI-checks to involve a formatting check in order to catch formatting errors automatically. - ## Caveats -Formatting tools are 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. +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 @@ -33,9 +29,13 @@ Formatting tools are do not always format code as you would like. Especially lin - [Continuous Integration keeps your project healthy](https://toolbox.basyskom.com/3) ## 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](https://wiki.qt.io/Qt_Coding_Style). +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](https://wiki.qt.io/Qt_Coding_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 IDE to apply coding styles while writing (in QtCreator: `Options > C++ > Code Style`). +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