Skip to content

Guide: Coding Guidelines

Jump to bottom
Valerio edited this page Dec 19, 2025 · 3 revisions

Guide: Coding Guidelines

Purpose

To ensure code consistency and readability across the project.

Prerequisites

  • Basic C++ knowledge.

Scope

Covers naming conventions, file structure, and formatting tools (clang-format).

Tudat has been developed by many contributors over a number of years, and so minor variations in coding style may appear from time to time. By following the guidelines below, you help ensure that the codebase remains as consistent and readable as possible for everyone involved.

Note

The tudatpy repository now contains both the C++ core library (tudat) and the Python bindings. The C++ exposure modules in tudatpy may use slightly different naming conventions (e.g., expose_*.cpp) compared to the core library files, but should still follow the general principles outlined below.

  1. File and Directory Names

    • Match Class or Module Names (with first letter lowercase)
      Where practical, name files after the primary class or module they contain, but start the filename with a lowercase letter. For instance, if a file defines the class SingleArcDynamicsSimulator, name it:
      singleArcDynamicsSimulator.h and singleArcDynamicsSimulator.cpp Likewise, if your main class is TabulatedAtmosphere, use:
      tabulatedAtmosphere.h and tabulatedAtmosphere.cpp

    • Aggregator (Umbrella) Headers Use snake_case
      If you create a header whose sole purpose is to collect/includes multiple other headers (e.g., earth_orientation.h that pulls in earthOrientationCalculator.h, eopReader.h, etc.), name that file in lower_snake_case. For example:

      // earth_orientation.h
#ifndef TUDAT_EARTH_ORIENTATION_H
#define TUDAT_EARTH_ORIENTATION_H

#include "earthOrientationCalculator.h"
#include "eopReader.h"
...

#endif // TUDAT_EARTH_ORIENTATION_H

      This file acts as a single include entry point for the entire earth_orientation submodule.

    • Directory Structure
      Folders group related functionality (e.g. astro, basics, io, simulation). Keep directory names short, lowercase, and descriptive.

  2. Namespaces

    • All lowercase: 
      namespace tudat
{
namespace simulation_setup
{
    // ...
}
} // namespace tudat
    • Multiple Levels:
      Deeper namespaces further categorize functionality (e.g. tudat::numerical_integrators, tudat::simulation_setup, etc.).

  3. Classes and Structs

    • PascalCase:
      Use UpperCamelCase (PascalCase) for class and struct names. 
      class SingleArcDynamicsSimulator
{
    // ...
};

struct StateDerivativeModel
{
    // ...
};
    • Header Guards:
      Use uppercase with underscores: 
      #ifndef TUDAT_SINGLE_ARC_DYNAMICS_SIMULATOR_H
#define TUDAT_SINGLE_ARC_DYNAMICS_SIMULATOR_H

// ...

#endif // TUDAT_SINGLE_ARC_DYNAMICS_SIMULATOR_H

  4. Functions

    • Lower Camel Case:
      Write function names in lowerCamelCase. 
      double computeGravitationalParameter(
    const double universalConstant,
    const double mass );
    • Verb-Based Naming:
      Use descriptive verbs (compute, calculate, create, get, set) to convey intent.

  5. Variables

    • Lower Camel Case:
      Local variables, parameters, and member variables typically use lowerCamelCase. 
      double currentTime = 0.0;
double stepSize = 60.0;
    • Private Data Members:
      You may see an underscore appended to private member variables (e.g., someValue_). This is common but not strictly universal across all files.

  6. Constants and Enumerations

    • UPPER_CASE for constants with underscores: 
      const double SPEED_OF_LIGHT = 299792458.0;
const double EARTH_GRAVITATIONAL_PARAMETER = 3.986004418e14;
    • Enums: 
      enum class BodyProperty
{
    MASS,
    RADIUS,
    GRAVITATIONAL_PARAMETER
};

  7. Code Documentation

    • Doxygen-Style Comments:
      Document classes, methods, and functions using Doxygen conventions: 
      //! Get the gravitational parameter of the central body.
/*!
 *  This function returns the gravitational parameter of the
 *  central body used in the simulation.
 */
double getGravitationalParameter() const;
    • Clarity Over Brevity:
      Provide concise yet clear descriptions for maintainability.

C++ Code Formatting with Clang-Format

tudat-bundle uses clang-format to enforce a consistent code style. This is done automatically on every PR by the Github Action Clang-Format Check and Fix, but we recommend to always format the code before every PR. The configuration file is located in the root of the repository as .clang-format.

Prerequisites

Ensure clang-format is installed. You can check the installation by running:

clang-format --version

If it's not installed, install clang-format using a package manager:

  • On Ubuntu/Debian: sudo apt install clang-format
  • On macOS: brew install clang-format
  • On Windows: Download and install from LLVM's official site.

Configuration File

This .clang-format file configures formatting settings, including indentation width, brace wrapping, spacing rules, and alignment settings. These settings will ensure your code remains organized, readable, and consistent with tudat code style.

Usage

1. Running Clang-Format on a Single File

To format a single file, run:

clang-format -i path/to/your/file.cpp

The -i flag formats the file in place.

2. Running Clang-Format on Multiple Files

To format all .cpp and .h files in your project directory:

find path/to/your/project -name '*.cpp' -o -name '*.h' | xargs clang-format -i

Alternatively, if you're using an IDE like Visual Studio Code, you can configure it to automatically format on save.

3. Setting Up Automatic Formatting in VSCode

If you’re using Visual Studio Code, you can automate code formatting:

  1. Install the Clang-Format extension from the marketplace.
  2. Open your project’s Settings (File > Preferences > Settings).
  3. Search for Clang-Format and set the path to your .clang-format file.
  4. Enable Format on Save by setting "editor.formatOnSave": true in your settings.json.

For a complete guide on configuring VSCode for Tudatpy development, see Guide: Alternative Build Procedures (CLion and VScode).

4. Checking Format Without Applying

To preview formatting changes without modifying files, run:

clang-format -output-replacements-xml path/to/your/file.cpp

This will show XML output if there are any format issues. You can then decide to apply formatting manually.

Clone this wiki locally