|
|
# Formatting
|
|
|
|
|
|
The easiest way to get the correct formatting is setting up `clang-format-12`. With the provided `.clang-format` file the files then can be formatted correctly.
|
|
|
The easiest way to get the correct formatting is setting up `clang-format-14`. With the provided `.clang-format` file the files then can be formatted correctly.
|
|
|
On unix-based system there are helper scripts in the `scripts` folder:
|
|
|
- `check-format-cpp.sh`: checks if all C++ files are correctly formatted
|
|
|
- 'format-cpp.sh`: formats all C++ files according to the formatting guidelines
|
|
|
|
|
|
# Naming conventions
|
|
|
|
... | ... | @@ -21,12 +24,49 @@ The following naming conventions should be followed when contributing. These con |
|
|
Exceptions:
|
|
|
- slot names: `on_snake_case`
|
|
|
|
|
|
# Commenting Code
|
|
|
|
|
|
For documenting our code we use [`Doxygen`](https://www.doxygen.nl/manual/docblocks.html). It can later by exported in various formats. We decided to use the following conventions, these should be added in the `.cpp` files:
|
|
|
|
|
|
```cpp
|
|
|
/**
|
|
|
@brief Here is a short description in one line.
|
|
|
|
|
|
Here is the place for a longer description. This can also span over multiple sentences.
|
|
|
|
|
|
@see otherClass
|
|
|
@todo a todo
|
|
|
@bug a known bug
|
|
|
@warning warning in usage (c will be overwritten!)
|
|
|
|
|
|
|
|
|
@param[in] a Description of input parameter a
|
|
|
@param[out] b Description of output parameter b
|
|
|
@param[in,out] c Description of in-/output parameter c
|
|
|
@return Description of the return value
|
|
|
*/
|
|
|
int Petrack::myFunction(int a, int b, myClass& c){...}
|
|
|
|
|
|
/**
|
|
|
* Long description of the member
|
|
|
*/
|
|
|
double foo;
|
|
|
|
|
|
int var; ///< Brief description after the member
|
|
|
```
|
|
|
|
|
|
It is also possible to add descriptive comments to classes, enums, files. The Doxygen comments then start with:
|
|
|
- `@class ClassName`
|
|
|
- `@enum EnumName`
|
|
|
- `@file fileName`
|
|
|
|
|
|
For adding formulas with LaTeX to the comments, you can use `f$ ... f$` for inline formulas and `f\[ ... f\]` for blocks.
|
|
|
|
|
|
# Refactoring Guidelines
|
|
|
|
|
|
In the course of finished any task, you will most likely touch some legacy code. If you do more than renaming something, please also make sure to fix following issues:
|
|
|
In the course of finishing any task, you will most likely touch some legacy code. If you do more than renaming something, please also make sure to fix following issues:
|
|
|
- comments:
|
|
|
- missing doxygen description of function
|
|
|
- missing Doxygen description of function
|
|
|
- translate comments to English
|
|
|
- remove any commented out code, which is not needed anymore (thanks to git it is never lost completely)
|
|
|
- code style:
|
... | ... | @@ -35,6 +75,8 @@ In the course of finished any task, you will most likely touch some legacy code. |
|
|
- improve variable names
|
|
|
- check if function can be made `const` or `static`
|
|
|
|
|
|
|
|
|
|
|
|
<!---
|
|
|
Copied from todo.txt:
|
|
|
```
|
... | ... | @@ -52,4 +94,5 @@ Programmierhinweise: |
|
|
- was bei weitergabe benoetigt wird steht unter seyfriedVers1
|
|
|
- von qt sind sources unter src komplett einsehbar
|
|
|
```
|
|
|
--> |
|
|
\ No newline at end of file |
|
|
-->
|
|
|
|