How do you ensure your ROS code is readable and maintainable?

2 Organize your packages and files

A good way to structure your ROS code is to use packages and files that follow the recommended layout and naming schemes. A package is a collection of nodes, libraries, and resources that perform a specific function or task. A file is a unit of code that contains a node, a library, or a configuration. You should use descriptive and meaningful names for your packages and files, and avoid using abbreviations or acronyms that are not widely known. You should also group related packages and files in subdirectories, and use CMakeLists.txt and package.xml files to define the dependencies, build options, and metadata of your packages.

3 Document your code and interfaces

Another essential aspect of writing readable and maintainable ROS code is to document your code and interfaces. Documentation helps you and others understand the purpose, functionality, and usage of your code, as well as the inputs and outputs of your nodes, topics, services, actions, and parameters. You should use comments and docstrings to explain your code logic, algorithms, and variables, and use tools like Doxygen, Sphinx, or rosdoc_lite to generate documentation from your code. You should also use roslaunch, rosparam, and rosbag to create launch files, parameter files, and data files that describe and configure your nodes and interfaces.

4 Use ROS tools and libraries

ROS provides a variety of tools and libraries that can help you write more readable and maintainable code. For example, you can use roscpp or rospy to write nodes in C++ or Python, and use the standard ROS messages, services, and actions to communicate between nodes. You can also use rostest and roslaunch to test and launch your nodes, and use rosbag and rviz to record and visualize your data. Additionally, you can use ROS libraries like tf, actionlib, or moveit to perform common tasks like coordinate transformations, action execution, or motion planning.

5 Follow design patterns and principles

Finally, you can improve your ROS code readability and maintainability by following some design patterns and principles that are widely used in software engineering. For example, you can use the publisher-subscriber pattern to decouple your nodes and topics, and use the service-client pattern to request and respond to synchronous calls. You can also use the action-server pattern to execute and monitor long-running tasks, and use the parameter-server pattern to store and retrieve global parameters. Moreover, you can apply the SOLID principles to design your code in a way that is modular, reusable, and extensible.

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?