C++ Coding Style

This topic contains the SDK C++ formatting and coding guidelines.

These guidelines are not written in stone! Start a discussion if you have suggestions for improvement (the project will consider anything other than "matters of personal taste").

Formatting and White Space

All .cpp and .h files should be formatted according to the .clang-format style.

Fix style

To automatically fix the formatting, run the command:

./tools/fix_style.sh .

If you don't have clang-format version 9.0 or later installed, you can use a docker image or install it as explained below:

Use clang-format in docker

You can just use the pre-built docker image:

tools/run-docker.sh tools/fix_style.sh .

Install clang-format

You need to have at least clang-format installed.

macOS

Install clang-format using brew:

brew install clang-format

Ubuntu 18.04

Install clang-format-9:

sudo apt-get install clang-format-9

Ubuntu 16.04

You need to add the llvm repository to install clang-format-9:

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -
apt-add-repository "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-9 main"
apt-get update
apt-get install clang-format-9

General Guidelines

The following general guidelines should be used for all code:

C++11 is encouraged to allow developers to use C++11 features and the standard library. Examples:
using namespace std is discouraged (read why). If needed specific declarations can be used in the source files such as using std::this_thread::sleep_for to reduce verbosity.
The usage of namespacing wherever possible is encouraged (e.g. enum class is to be used over enum).
Filename extensions should be .h for header files and .cpp for source files (for consistency).
Variable and method names should err on the side of verbosity instead of being quick to type and read. Abbreviations are only to be used for small scopes and should not be exposed in public APIs.
All variables that have a physical unit should have the unit in the variable name (e.g. _m for meters, _m_s for meters/second).
Variable and method names should be snake_case and class/struct/enum names CamelCase. Private variables should start with an underscore, e.g.: _variable_name.
Try to exit functions early instead of nesting ifs (read why).
We don't use exceptions but use error codes. There are pros and cons for exceptions but given that the public API should be as simple as possible, it makes sense to refrain from exceptions altogether.

Coding Style