Guides›General›

Code Conventions

Conventions used in NUbots code.

Updated Last updated 4 Dec 2024

Edit

Naming Conventions

Case

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

Scenario	Case Type	Example
Class name	PascalCase	`MyClass`
Function name	snake_case	`my_function()`
Variable name	snake_case	`my_variable`
Constants	SCREAMING_SNAKE_CASE	`MY_CONSTANT_VARIABLE`
`yaml` fields	snake_case	`my_field: 0.0`

JavaScript conventions are in the below table.

Scenario	Case Type	Example
Class name	PascalCase	`MyClass`
Function name	camelCase	`myFunction()`
Variable name	camelCase	`myVariable`
Constants	SCREAMING_SNAKE_CASE	`MY_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 name	Description
`Hab`	Denotes a 3D affine transformation matrix going from space $b$ to space $a$ .
`Rab`	Denotes a 3D rotation from space $b$ to space $a$ .
`rABb`	Denotes a vector from point $B$ to point $A$ in space $b$ .
`uABb`	Denotes a unit vector from point $B$ in the direction of point $A$ in space $b$ .
`vBb`	The velocity of $B$ in space $b$ .
`vABb`	The velocity of $B$ towards A in space $b$ .
`aBb`	The acceleration of $B$ in space $b$ .
`aABb`	The acceleration of $B$ towards $A$ in space $b$ .

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.

The directives are used by doxygen to create the codedocs.

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:

Directive	Description
`@brief`	A 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`.
`@details`	All 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.
`@return`	Details 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.
`@author`	The 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.

Directive	Description
`@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.
`@attention`	Tells the reader that they should pay attention to the following point.
`@warning`	Tells the reader something that may go wrong followed by preventative measures they can take.
`@note`	Extra information that does not fit in other tags.
`@remark`	An aside or candid comment about the code or approach.
`@todo`	Adds a todo to the documentation.
`@post`	Details a post condition.
`@pre`	Details a pre condition.
`@code{.<language>}` and `@endcode`	starts 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 `@endverbatim`	Starts 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;
}

On this page