Coding Best Practices

This page talks about coding best practices (according to RoboNav). This is what is expected before your code can be merged into the master branch! As our codebase grows, it's important that it is well-documented and easy to use by others.

Comments

Your functions should be commented. We generally put function comments in header files (these end in .hpp). Here's a good example:

/**
  * @brief Calculate the intersection of a line segment and a circle.
  * The derivation of the formula can be visualized here: https://www.desmos.com/calculator/vatao173by.
  * This assumes that the circle is centered at the robot's pose and both points are in the robot frame.
  * @param a The first point of the line segment in the robot frame
  * @param b The second point of the line segment in the robot frame
  * @param r The radius of the circle
  */
geometry_msgs::msg::Point circleSegmentIntersection(const geometry_msgs::msg::Point & a, 
    const geometry_msgs::msg::Point & b, double r);

Each comment begins with a @brief which summarizes the utility of the function. What is it used for? If it requires some hardcore math, how does it work? And perhaps more importantly it states all assumptions that were made.

Note

Notice how this comment states clearly that the points a and b are in the robot's reference frame. This is super important!

The @brief tag is followed by a @param tag for each argument describing what it is.

Pull Requests

Ideally, pull requests (PRs) should be less than 500 lines of code. However, large infrastructure changes are an exception.

You should title your pull request with the following format.

[category] overview of changes

For example, if your PR adds an implementation of the theta* path planning algorithm to the navigation stack, your PR would be titled something like:

[navigation] adds theta* path planning implementation

This makes it easier to understand what code your PR modifies, and what functionality is added or modified. If your PR is still a work in progress, it should either be a draft PR or have WIP as the category.

C++ Styling

We strongly recommend taking a look at Google's C++ Style Guide for industry standard practices for C++ formatting.