Code Style - umrover/mrover-ros GitHub Wiki

Formatting

Run ./style.sh in the top-level directory. ./style.sh --fix will attempt to auto-format.

General

  • Prefer longer variable names. Avoid abbreviations. We have autocomplete for a reason!

C++

  • Adhere to all clang tidy checks defined in .clang-tidy. This is tested by the CI.
  • Style syntax with the clang format defined by .clang-format. This is tested by the CI.
  • Never use raw pointers, prefer smart pointers (usually std::shared_ptr).
  • Check if something exists in the standard library before you reinvent the wheel!
  • Prefer static_cast etc. instead of C style cast
  • Use auto on iterator types (ranged for) and when the type is obvious, for example casting or std::make_shared
  • Pass primitives by value (int, float, etc.) and complex types by reference or smart pointers
  • Do not use references (&) types for out parameters in functions, prefer returning a struct
  • Prefer using an explicit struct instead of std::pair or std::tuple
  • Use structured binding when possible (e.g. iterating named map, unpacking a std::pair, ...)
  • Avoid std::bind, use an explicit lambda

Python

  • Currently black and mypy are used. This is tested by the CI.
  • If you are writing a function, please use type hinting for the signature. For other places, only use if necessary, for example a situation where the types are confusing.
  • Black is an autoformating tool that will control the format of your code
  • MyPy is a static type analysis tool that will make sure you don't violate type hinted functions
  • Document your code! Use the reST standard specifically

Here is a good concrete example:

def pos_distance_to(self, p: SE3) -> float:
    """
    Get the euclidean distance from the position of this SE3 pose to the position of another SE3 pose.
    :param p: another SE3 pose object
    :returns: euclidean distance between the two SE3 poses
    """
    return np.linalg.norm(p.position_vector() - self.position_vector())

Vue.js

  • The tools that we use for style checking and formatting with VueJS are eslint and prettier.
    • eslint is a style checking tool that enforces good style for the actual text of the code in order to make it as maintainable as possible
    • prettier is a tool to format our code to be more readable
    • Both tools should be installed automatically with yarn when you run the GUI, but if they do not work, you can run the mrover/src/teleop/gui/gui_install.sh bash script to ensure that they will be installed
    • To run them, inside of the mrover/src/teleop/gui/ directory you can run the following commands:
    yarn run lint         # To check and fix ESLint issues (ESLint only autofixes certain issues)
yarn run lint-check   # To check but not fix ESLint issues
yarn run format       # To check and autoformat with prettier
yarn run format-check # To check if files are prettier formatted
  • It is highly reccomended that you install the ESLint and Prettier-ESLint VSCode extensions if VSCode is your editor of choice
    • The ESLint plugin will automatically display ESLint style errors in your code and link you to the rules it is trying to enforce: image
    • The Prettier ESLint plugin will automatically format the code with the Prettier formatting style as well as autofix all of the ESLint issue that it can fix.
    • You can use the Prettier-ESLint plugin by:
      • Right clicking anywhere in your file and selecting Format Document With...
        image
      • And selecting Prettier ESLint from the menu that pops up
        image