Code Conventions

Conventions used in NUbots code.
Updated 26 Jan 2022

Naming Conventions

Case

NUbots code case conventions are in the below table. It does not include JavaScript, which is in the following table.

ScenarioCase TypeExample
Class namePascalCaseMyClass
Function namesnake_casemy_function()
Variable namesnake_casemy_variable
ConstantsSCREAMING_SNAKE_CASEMY_CONSTANT_VARIABLE
yaml fieldssnake_casemy_field: 0.0

JavaScript conventions are in the below table.

ScenarioCase TypeExample
Class namePascalCaseMyClass
Function namecamelCasemyFunction()
Variable namecamelCasemyVariable
ConstantsSCREAMING_SNAKE_CASEMY_CONSTANT_VARIABLE

Mathematics

Conventions for variables representing vectors and homogeneous transformations are explained in the Linear Algebra section of the Mathematics page.

A summary is given in the table below.

Variable nameDescription
HabDenotes a 3D affine transformation matrix going from space bb to space aa.
RabDenotes a 3D rotation from space bb to space aa.
rABbDenotes a vector from point BB to point AA in space bb.
vAbThe velocity of AA in space bb.

Documentation

We use tokens called "directives" or "tags" to annotate different parts of a comment with rich metadata. These directives start with @ or \ (@ is preferred) and are followed by the directive name, arguments (for some directives), and a single line of description.

When writing modules, the .hpp should include a documenting comment for each class, struct, function, method, global variable, member variable and anything extra that you think may need one.

Directives

These are some common directives:

DirectiveDescription
@briefA brief description of the following code. Every documenting comment should have this. If the first line does not have a directive it is treated as @brief.
@detailsAll the details that someone using this thing might need to know beyond what is provided in other directives. Comment lines after the initial one but before any directive are treated as @details.
@param[direction] <formal name>Details a parameter that is passed to a function. Direction is either in or out and is usually omitted.
@returnDetails what a function returns.
@retval <value>Details specific return value meanings, usually for enums, booleans or error codes.
@throws <type name>Details what a function throws.
@tparam <formal name>Details a template parameter, usually a named requirement or other requirements that must be fulfilled.
@authorThe author and maintainer of this code. Git blame is unreliable as some changes could just be formatting.

This is a list of less common directives that may be used.

DirectiveDescription
@example <file-name>Indicates that an example of how the function or class should be used is at <file-name>.
@see <name>Links to the documentation for another class, function or variable.
@attentionTells the reader that they should pay attention to the following point.
@warningTells the reader something that may go wrong followed by preventative measures they can take.
@noteExtra information that does not fit in other tags.
@remarkAn aside or candid comment about the code or approach.
@todoAdds a todo to the documentation.
@postDetails a post condition.
@preDetails a pre condition.
@code{.<language>} and @endcodestarts and finishes a code block respectively, similar to ` in NUbook. {.language} is optional.
@copydoc <name>Copies the documentation from another thing.
@f$, @f[, @f], @f{<environment>}{ and @f}Creates latex doxygen formulas.
@verbatim and @endverbatimStarts and finishes verbatim output respectively, which outputs exactly what you write.

See the Doxygen documentation for the full list.

Extra formatting

HTML can be used, but should be kept to simple tags like <b> and <em>. See the official documentation for a full list of available HTML tags.

Example

This example shows more than we normally require, but tries to give an example of how most directives can be used.

/**
* @brief Represents a robot in the simulation environment
* @details As far as the simulation is concerned, robots have only two behaviours: move and make a sound. This class supports modelling both behaviours.
* @tparam T The robot's type of motion (walk, roll, etc), should be a subtype of the #Motion class
* @tparam U The type of sound the robot makes, should be a subtype of the #Sound class
*/
template <typename T, typename U>
class SimulationRobot {
/// @brief The name of the robot, should be unique across all robots in the simulation
private std::string name;
/// @brief How loud the robot sounds, in decibels
/// @see AudioEngine::playback() and Sound::default_volume
private int sound_volume = 60;
/**
* @brief Check if the robot has moved since the given timestamp
* @param timestamp The timestamp (in milliseconds of simulation time) to check for motion after
* @throws NotFoundError The robot object was not found in the current simulation world
* @return Whether or not the robot has moved since the timestamp
* @retval true The robot has moved since the timestamp
* @retval false The robot has not moved since the timestamp
*/
[[nodiscard]] bool has_moved_since(const int& timestamp) const;
}

Future

In the future we are planning to use a combination of Doxygen and our NUClear mapper for automatic low level documentation of our code, which will be included in NUbook.

Copyright © 2022 NUbots - CC-BY-4.0
Deploys by Netlify