Code Formatting
Table of content
1. Introduction
2. Formatting
2.1 Available options
2.2 Reformat code
2.3 Reformat code with options..
2.4 Reformat JSON
2.5 Reformat XML
2.6 Reformat Comment Paragraph
3. Troubleshooting
3.1 The clang-format executable has not been found
1. Introduction
Having a tool that will take care of unifying code formatting within the code base is crucial for any software project aspiring to be successful. Having unified code formatting allows a development team to save a significant amount of time by avoiding unnecessary discussions during code review. Also, with the whole process automated, you do not need to think about the style and can focus on other things, such as the architecture of your application.
Our implementation of code formatting is based on clang-format. This is an industry standard-tool widely used among C/C++ developers. It not only supports C++, but other languages as well, such as C, C#, JavaScript, JSON, and Objective-C.
The current version of formatting was introduced in 2023.1 version.
2. Formatting
2.1 Available options
To reformat code, you can use several strategies:
Reformat code (Ctrl/⌘+I)
Reformat code with options.. (Ctrl/⌘+Shift+I)
Reformat JSON
Reformat XML
Reformat comment paragraph (Alt/⌃+R)
In this paragraph, we will discuss each of these options separately. The above code formatting options can be found in the "Assist -> Reformat" menu.
Please notice that access to the "Reformat" menu is also available directly from the "Edit" menu. It is an alternative pathway. It doesn't matter which reformat menu you use. The functionality is exactly the same.
All options available in the "Reformat" menu take into account your selection. It means that whenever you have selected some portion of text in the code editor, the reformat commands will only operate on that text. If there is no selection, the commands will operate on the whole file's content.
2.2 Reformat code
As the name of the option suggests, this option formats code. By default, this operation looks for a .clang-format file located in your code base. The file is formatted according to the information about style stored in it.
U++ has its own .clang-format file. The style is based on LLVM. However, there are several modifications to it, so the whole style has its own name. We call it simply U++ style. If you want to study this file on your own, you can find it in our main repository. All applications that are built within the uppsrc assembly are using this style by default, and there is no need for additional configuration.
If you want to override the default U++ .clang-format file, you can create your own and put it in your assembly or package. Then "Reformat code" will use it as a base for the code formatting operation. The documentation about creating your own .clang-format file can be found here.
If no .clang-format file is provided and the application is not developed within valid uppsrc assembly, then the "Reformat code with options.." option is executed.
2.3 Reformat code with options..
This option opens a separate dialog in which you have direct access to all options provided by clang-format. It is also less straightforward than the "Reformat code" option because it allows you to preview code formatting before applying it to code. If you don't like the final result, you can always cancel the operation by clicking the dedicated button.
As you can see in the above image, the dialog is very advanced. It allows you to experiment with all the options that can be used in .clang-format file. You can easily create your own style and export it by using the "Save.." button. Once you export .clang-format file, you can use it in one of your projects.
2.4 Reformat JSON
This option, as the name suggests, formats JSON. It is based on our internal JSON format implementation. The outputted JSON is always the same. There are no configuration options.
Please notice that for formatting JSON, you can use the "Reformat Code" option. This option offers much more flexibility because you can configure output directly in .clang-format file.
2.5 Reformat XML
The same as reformat JSON, but dedicated to XML.
2.6 Reformat Comment Paragraph
This option formats comments. It means that it will optimize the size of the comment to the optimal level. By default, it formats the comment where the caret is placed. It also works with selections.
If there is no need for comment formatting, nothing happened.
The sample code transformation made by this option is shown in the below image:
3. Troubleshooting
3.1 The clang-format executable has not been found
TheIDE uses an external clang-format executable. When TheIDE could not find this executable, errors occurred. To avoid this error, please make sure that the clang-format executable is installed and available in your environment. You can verify it by entering the clang-format command in your terminal.
Please notice that for the Windows platform, TheIDE is first looking for clang-format executable bundled with the U++ installation and stored in the bin directory.
|
