97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
# Contributing guidelines
|
||
The main goal of the following document is to have a `basic set of guidelines` that all contributors should apply when writing code in the `status-desktop` project and specific rules for using the C++ language in order to achieve consistent, maintainable and easy-to-understand code for everyone.
|
||
|
||
There are lots of existing and extended guidelines that can be used, as well, as a complement of the ones that will be described below. Here some examples:
|
||
- [Cpp Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)
|
||
|
||
## Generic rules
|
||
|
||
General software development best practices and / or OPP specific ones:
|
||
- Write code using a syntax that can make the `code easy to understand` although it requires more writing. The time spent to understand that code by other contributors will be compensated.
|
||
- Create `self-documented` code by using self-explanatory names wherever possible for classes, methods and variables. It will increase readability and comprehension.
|
||
- Keep in mind the `SOLID` principles. Your code will become flexible, reusable, scalable and prepared for test-driven development.
|
||
- Keep `methods body short`. Divide when possible. Recursive calls and nested loops should be minimized.
|
||
- Use `parenthesis` to resolve ambiguity in complex expressions. Each individual expression should be written in its single parenthesis.
|
||
- Use the following `arguments order` in method's `signature` (it will force default argument's values to be input ones):
|
||
- Input / Output.
|
||
- Output.
|
||
- Input.
|
||
- `Initialize` all `variables` when declared.
|
||
- `Initialize` all class `attributes` in their own class constructor.
|
||
- Use `m_` syntaxis to define attribute names.
|
||
- Class and method names should begin with `capital letter` and use `camel case` approach.
|
||
- Use the following `class / members declaration structure`:
|
||
- Public methods / members.
|
||
- Protected methods / members.
|
||
- Private methods / members.
|
||
- Code should compile `without warnings`.
|
||
|
||
|
||
## C++ language specific rules
|
||
- As a general rule, for `smart pointers`, `containers` and `threads`, use `STL for domain` and `Qt specific for controllers` (layer exposed to QML).
|
||
- Use smart pointers for general dynamic/heap memory management: STL with make_shared and make_unique.
|
||
- Use Qt’s parent-child relationship and built-in ownership in API where appropriate: QObject-based with QPointer.
|
||
- Use `const` keyword wherever possible it will build a more robust code. If it is used in variables, the held value cannot be modified; in pointers, the address pointed to cannot be modified (no restrictions for the stored data); in class methods, the method cannot modify any class attribute.
|
||
- When passing arguments, use `references` instead of pointers as far as possible by using `&`. It will prevent some typical errors such as passing null pointers to methods.
|
||
- When passing arguments, `avoid passing by value` big size arguments as structures and objects. It will reduce the stack used and it will not be necessary to have properly implemented the copy constructor in all classes.
|
||
- Use `dynamic allocation` only if needed because it requires much processor time than stack memory allocation. By minimizing its usage for variables and objects will increase efficiency and `reduce` the risk of `memory leaks`.
|
||
- `Thread’s` usage must be `justified`. Always keep in mind the principle “Keep It Simple”.
|
||
- The `C++ standard` to be used must be `at least C++17`.
|
||
- `Singleton’s` usage must be `justified`. They must be just only global settings and specific objects but to use them it will need a consensus with the team.
|
||
- `.clang-tidy` configuration will be used as the C++ linter and at least the following checkers will be set (it must be included in the CI process):
|
||
- cppcoreguidelines-*
|
||
- modernize-*
|
||
- readibility-*
|
||
|
||
## Documentation
|
||
|
||
- Use `header files` to document classes and methods by using `doxygen syntax`. More information here: [Doxygen manual](https://www.doxygen.nl/index.html).
|
||
|
||
|
||
```
|
||
/*
|
||
* Add here header file description.
|
||
* \file Example.h
|
||
* \brief Source code file.
|
||
*/
|
||
|
||
...
|
||
|
||
/*
|
||
* \brief Add here short class description.
|
||
* This class implements a ...
|
||
*/
|
||
class Example {
|
||
public:
|
||
/*
|
||
* \brief Class constructor
|
||
*/
|
||
Example();
|
||
|
||
/*
|
||
* \brief Class destructor.
|
||
*/
|
||
~Example();
|
||
|
||
protected:
|
||
/*
|
||
* \brief Add here short method description.
|
||
* This method ...
|
||
* \return True if the operation was successfully completed; False otherwise.
|
||
*/
|
||
bool Example2();
|
||
|
||
private:
|
||
/*
|
||
* \brief Add here short method description.
|
||
* This method...
|
||
*/
|
||
Example3(bool bEnabled //!< [in] Enable argument value.
|
||
);
|
||
|
||
...
|
||
}
|
||
```
|
||
|
||
|