******************
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
:doc:`references/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 <clang_format_config_>`__.

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:

.. code-block:: bash

   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.



.. _black: https://black.readthedocs.io/en/stable/
.. _PEP 8: https://peps.python.org/pep-0008/
.. _Google style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
.. _clang_format_config: https://github.com/machines-in-motion/mpi_cmake_modules/blob/master/resources/_clang-format