... | ... | @@ -456,6 +456,40 @@ TODO: Add more guidelines from MISRA |
|
|
* Do not use the C++ style [Expects( ) and Ensures( )](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-expects)
|
|
|
* We want our code to gracefully fail and not run into exceptions that it cannot handle. Whenever there is doubt, always assume you are designing a safety critical controller that is responsible to ensure that a car’s driver would always be able to apply the brakes correctly on the vehicle.
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
* [Code should be self-documenting](#markdown-header-expressive-code)
|
|
|
- Although, there may be code such as mathematical formulas that still require a comment to explain the intent of the code. In this case, make sure to write the comment at the time the code is written
|
|
|
- Comments can be used to explain the intent of the code if self-documentation is not sufficient
|
|
|
* **Include all separator comment blocks** (even when there is no content below them) such as:
|
|
|
- `Defines`, `typedefs` etc.
|
|
|
- Please see coding file templates and example structure below
|
|
|
* Use `/**` to document multi-line comments for Doxygen
|
|
|
- For consistency, header files (public APIs) should always do this over `/*`
|
|
|
- This is for consistency and also because Lint/MISRA does not like multi-line comments using `//`
|
|
|
- Documentation is mandatory for public facing interfaces and optional everywhere else.
|
|
|
- See [Doxygen Tags](http://www.doxygen.nl/manual/docblocks.html)
|
|
|
* Doxygen doesn’t like documenting `static inline` functions so do not use them
|
|
|
- This is also discouraged because `inline` functions cannot be mocked during unit-testing, as mentioned previously
|
|
|
|
|
|
### Header File Documentation
|
|
|
|
|
|
* For consistency, always use only two types
|
|
|
* `/**` style for functions or documentation prior to a construct
|
|
|
* `///< ` for documenting something on the same line
|
|
|
* Do not mix of `///` and `/**`
|
|
|
* The header file looks more consistent this way
|
|
|
|
|
|
### Doxygen
|
|
|
* Do not use `@brief`
|
|
|
- It simply starts a new paragraph.
|
|
|
- It has no effect on the documentation. If you want multiple paragraphs, separate them by an empty line
|
|
|
* Do not use `@file my_file.h`
|
|
|
- Doxygen knows your file's name so follow the `DRY` principle
|
|
|
* If there is no parameter or return type, then do not use `@param none` or `@return none` respectively
|
|
|
- `@param` is only needed for parameter names that are not clear
|
|
|
- If the variable is very clear and explicitly named, there should be no need for explaining the parameter. If someone does still explain the parameter for whatever reason, we don’t need to spend any time pointing it out and/or having them remove the comment or amend their commit (all of which takes more time than just leaving a redundant comment in there).
|
|
|
|
|
|
----
|
|
|
# Thoughts and Decisions
|
|
|
## Relative Includes vs. Explicit Path includes
|
... | ... | @@ -1492,44 +1526,6 @@ static int wait_for_read(int socket, uint32_t timeout_ms) { |
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
|
# Documentation
|
|
|
|
|
|
* [Code should be self-documenting](#markdown-header-expressive-code)
|
|
|
- Although, there may be code such as mathematical formulas that still require a comment to explain the intent of the code. In this case, make sure to write the comment at the time the code is written
|
|
|
- Comments can be used to explain the intent of the code if self-documentation is not sufficient
|
|
|
* **Include all separator comment blocks** (even when there is no content below them) such as:
|
|
|
- `Defines`, `typedefs` etc.
|
|
|
- Please see coding file templates and example structure below
|
|
|
* Use `/**` to document multi-line comments for Doxygen
|
|
|
- For consistency, header files (public APIs) should always do this over `/*`
|
|
|
- This is for consistency and also because Lint/MISRA does not like multi-line comments using `//`
|
|
|
- Documentation is mandatory for public facing interfaces and optional everywhere else.
|
|
|
- See [Doxygen Tags](http://www.doxygen.nl/manual/docblocks.html)
|
|
|
* Doxygen doesn’t like documenting `static inline` functions so do not use them
|
|
|
- This is also discouraged because `inline` functions cannot be mocked during unit-testing, as mentioned previously
|
|
|
|
|
|
## Header File Documentation
|
|
|
|
|
|
* For consistency, always use only two types
|
|
|
* `/**` style for functions or documentation prior to a construct
|
|
|
* `///< ` for documenting something on the same line
|
|
|
* Do not mix of `///` and `/**`
|
|
|
* The header file looks more consistent this way
|
|
|
|
|
|
## Doxygen
|
|
|
* Do not use `@brief`
|
|
|
- It simply starts a new paragraph.
|
|
|
- It has no effect on the documentation. If you want multiple paragraphs, separate them by an empty line
|
|
|
* Do not use `@file my_file.h`
|
|
|
- Doxygen knows your file's name so follow the `DRY` principle
|
|
|
* If there is no parameter or return type, then do not use `@param none` or `@return none` respectively
|
|
|
- `@param` is only needed for parameter names that are not clear
|
|
|
- If the variable is very clear and explicitly named, there should be no need for explaining the parameter. If someone does still explain the parameter for whatever reason, we don’t need to spend any time pointing it out and/or having them remove the comment or amend their commit (all of which takes more time than just leaving a redundant comment in there).
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
|
# Code Templates
|
... | ... | |