OMPL Style Guide

This document provides a brief overview of OMPL coding standards. It is meant to assist developers who are contributing code to OMPL.

Spacing

• Each source block should be indented by 4 space characters. No tab characters should appear in source code.
• Each enclosing brace should reside on its own line, but braces can be omitted if the enclosed block consists of exactly one line.
• Each binary operator ('+', '-', '&', '=', '==', etc.) should be surrounded by spaces.
• The '*' and '&' in pointers and references in function/method arguments or variable declarations should be preceded by a space. They should not be followed by a space.

The following is an example of desirable code spacing.

int foo(int &n)
{
    for (unsigned int i = 0; i < n; ++i)
    {
        if (i % 2 == 0)
            std::cout << i << " ";
    }
}

Filenames & Macros

• Source filenames should begin each word with a capital letter, and there should be no underscores between words.
• Header files should use the .h extension, and implementation files should use the .cpp extension.
• Each implementation file should reside in a src/ directory, immediately below the directory containing the corresponding header file.
• Include guards in header files should be of the form OMPL_PATH_FILENAME_, where the words in the filename are separated by underscores.

For example, the header and implementation files in which ompl::RNG is defined are ompl/util/RandomNumbers.h and ompl/util/src/RandomNumbers.cpp, respectively. The header file begins with the include guard

#ifndef OMPL_UTIL_RANDOM_NUMBERS_

Functions & Classes

• Function names should begin with a lower-case letter and should begin each subsequent word with a capital letter, and there should be no underscores between words (e.g., ompl::base::StateSpace::setName()).
• Functions accepting no parameters should have void in place of a parameter list.
• Class names should begin each word with a capital letter, again with no underscores (e.g., ompl::base::StateSpace).
• Scoping directives (public, protected, private) should be at the same level of indentation as the class declaration.
• Class member variable names should begin with a lower-case letter and should begin each subsequent word with a capital letter. They should end with a single underscore (e.g., ompl::base::StateSpace::longestValidSegment_).
• Names of constants and static variables should be in all capital letters, with an underscore between each word (e.g., ompl::base::StateSpace::DEFAULT_PROJECTION_NAME).

For example, consider the following source code, which follows the above guidelines.

class SampleObject
{
public:
    SampleObject(void) : objectTag_(NUM_INSTANCES++)
    {
    }

    int getObjectTag(void) const
    {
        return objectTag_;
    }

    static int NUM_INSTANCES;

private:
    const int objectTag_;
};
int SampleObject::NUM_INSTANCES = 0;

Other Coding Guidelines

• Compiler specific features should never be used (avoid use of #ifdef).
• Code must compile without warnings.
• If a class member function can be marked const, then it should be marked const.
• Member functions marked as const must be thread safe. If a function is intended to be thread safe, it should be marked as const (one can use the mutable keyword if needed).
• All classes, methods and member variables must be documented (Doxygen style). High-level documentation can be written either in MarkDown format or in Doxygen format.
• Forward declaration of types should be done with the OMPL_CLASS_FORWARD() macro when shared pointers to the type are also needed: OMPL_CLASS_FORWARD() will define a shared pointer to the type using the Ptr suffix (e.g., ompl::base::StateSpacePtr).
• When passing objects as arguments to functions, the following convention should be used:
  • if possible, pass a const reference to the type; this means that a pointer to the object passed in will not be maintained and no changes need to be made to the object.
  • if changes need to be made to the object passed in, pass it by reference (non const).
  • if a pointer to the object needs to be maintained for later use, pass the the Ptr type as const T Ptr &. This maintains a shared pointer to the passed in object. However, this can create a dependency cycle (e.g., StateValidityChecker storing a shared pointer to SpaceInformation, which already stores a shared pointer to StateValidityChecker).
  • when a dependency cyle would be created, and often access to the pointer is needed, use a raw pointer. Use a const raw pointer if possible. If access to the pointer is not often required, using a weak pointer is good.