Table of Contents list

The main rule of the style guide is to preserve and follow the style of existing code.

Comments and documentation

Documentation

Documentation explains the public API to users, and important parts of the private API to other developers.

Write documentation above the declaration of classes, functions and variables. In most cases, this will be in the header files.

Documentation follows the Doxygen rules. Here's an example. Note the indentation. 

/**
 * @brief   Short overview of the function/class.
 * 
 * Elaborate explanation.
 * 
 * @note    Important remark.
 * 
 * @tparam  TemplateParameterName
 *          Template parameter documentation.
 * 
 * @param   parameterName
 *          Parameter documentation.
 * @param   anotherParameterName
 *          Parameter documentation.
 * 
 * @return  Explanation of what the function returns.
 */
For short functions, you can use a different style of comments: class="lineNumbers">/// Short explanation of what the function does.

Comments

For comments about the implementation of a function, write a short explanation of the approach you're using.
Between lines of code, explain what the line/statement is doing, if necessary.

Please take the time to add comments. If I can't understand your code, I cannot accept the pull request.

Code formatting

The repository contains a .clang-format file for auto-formatting the code. You have to format all files before committing them.
If you don't format the code before committing there will be many unintelligible changes on the next commit, when someone else edits the code and does apply the auto-formatter.

You can call the formatter using the CTRL+Shift+P menu, by selecting "Format Document".
I recommend assigning an easy keyboard short cut to this action, because you're going to use it all the time.

Unit tests

All code has to have some kind of unit tests, and all tests have to be run (and passed) before committing.
On top of that, all examples must compile successfully.

More information on tests can be found on the next page.