This document provides a brief overview of OMPL coding standards. It is meant to assist developers who are contributing code to OMPL.
- Note
- An automatic code formatter is available to automate enforcing the style guide, see below.
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.
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
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.
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 cycle 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.
Automatic Code Formatting
An automatic code formatter is available to automate enforcing the style guide, using clang-format. This set of tools can be used standalone via command line or with editor integrations.
Setup
Install clang_format. For Ubuntu:
sudo apt-get install -y clang-format
Usage
A configuration file is available at the base of the OMPL repository that will be automatically picked up by the following commands. You can run clang_format
in several ways:
Command Line
Format single file:
clang-format --i -style=file MY_OMPL_FILE.cpp
Format entire directory recursively including subfolders:
find . -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format --i -style=file $1
Emacs Editor Configuration
In your ~/.emacs
config file, add the following:
Format your source code if its in some directory such as the ompl
(feel free to change keywords ompl):
Set a keyboard shortcut to run, such as F12
(global-set-key [f12] 'run-ompl-clang-format)
Atom Editor Configuration
Install the clang-format package via the Atom package manager or apm install clang-format
.
In the package settings set clang-format-3.6
as your executable and point 'Style' to your .clang_format
file.
Other Editors
Please contribute instructions here.