3.1. Code Formatting Guidelines

Enforcing a consistent formatting has a few advantages:

  • No one needs to manually review code for most of these formatting issues, and people can focus on content.
  • A separate automatic script (see below) can be applied to re-establish the formatting after refactoring like renaming symbols or changing some parameters, without needing to manually do it all.

Below are the guidelines for formatting code in the various languages used for CELESTE development.

3.1.1. C++ Formatting Guidelines

The following list provides the general formatting/indentation rules for CELESTE code (C/C++):

  • Basic indentation is four spaces.
  • Keep lines at a reasonable length. Due to the natural complexity of the code, use 120 characters as a guideline. If you end up indenting very deeply, consider splitting the code into functions.
  • Never use tabs; use only spaces. Most editors can be configured to generate spaces even when pressing tab. Tabs (in particular when mixed with spaces) easily break indentation in contexts where settings are not exactly equal (e.g., in git diff output).
  • No trailing whitespace.
  • extern "C" and namespace blocks are not indented, but all others (including class and switch bodies) are.

Most of the above guidelines are enforced using clang-format, an automatic source code formatting tool. While it is a suitable tool for enforcing the basic rules, clang-format may not have enough formatting options to serve our needs over time, and so there is consideration to migrating over to uncrustify, which provides over 600 formatting rules.

3.1.2. Python Formatting Guidelines

Please refer to the formatting rules in the Python official PEP 8 Guidelines.