Contribution Guide

If you want to contribute code to the TriFinger repositories, please keep the following guidelines in mind. They are valid for all the repositories listed in Software Package Overview. Some, like code formatting, are automatically checked on pull requests, so you may only merge if those checks pass.

Code Style

General

  • Avoid abbreviations in variable/function/… names, rather use longer but more descriptive names. Example: joint_position instead of jnt_pos.

  • When a variable holds a value with a unit, consider adding that unit as suffix. Example: sleep_duration_ms, joint_position_rad.

  • Do not merge FIXME commands to the master branch. They are okay as a reminder during development on a feature branch but must be resolved before merging.

  • TODO comments are allowed but should be avoided if possible.

  • Never merge unsquashed fixup commits (generated by git commit --fixup) to master.

Python

All Python code must be formatted with black and should generally adhere to PEP 8 (except for the line length, which for some packages uses black’s default of 88).

Add docstrings to all classes and functions. Format them using Google style.

C++

C++ code must be formatted with clang-format, using the configuration shipped with mpi_cmake_modules.

When you have the mpi_cmake_modules package installed in your workspace (which is likely the case, as it’s a core dependency of the TriFinger packages), there is an executable mpi_cpp_format which will run clang-format with the correct configuration:

mpi_cpp_format path/to/package

Apart from that some basic style guide:

  • Class names start with a capital letter: MyAwesomeClass

  • Variables and functions use snake case: my_awesome_variable

  • Constants are ALL_UPPER_CASE

  • Use #pragma once in header files.

  • Add doxygen comments to all classes and functions.