Documentation Guidelines - lukasholtkamp/b.ob GitHub Wiki

Release

  • The "base" branch must always be executable.
  • When milestones are reached, a release must be created.
  • An up-to-date user guide must be available for each release.
  • An updated rough software architecture must be available for each release.

Feature development

  • New features to be developed can be created via issues and are tracked via the Projects->KanBan board.
  • Features are developed in separate branches.
  • Newly developed features are merged into the "base" branch via a pull request. At least one Reviewer is required.

Code Documentation

  • The functionality of each code function must be documented with at least one short sentence directly in the code.
  • The configuration file is in the docs folder in the base and can be generated by
doxygen dconfig
  • Tool: Doxygen

Folder structure

  • bob_base: Contains the ROS2 control hardware components for Bob. This can be thought of as a function which takes in command velocities and outputs this to the motor drivers.
  • bob_bringup: Contains launch files to call the needed nodes to run bob and configuration files to change driving behaviour.
  • bob_description: Contains the URDF description files for bob and ros2 control.
  • bob_teleop: Contains configuration and launch files used to enable joystick control of bob.
  • bob_lidar: Contains configuration and launch files used for the Lidar.
  • bob_simulation: Contains launch files, Gazebo worlds and configurations files needed for the Simulation.
  • bob_slam: Contains configuration, launch files and the saved maps captured from running SLAM.
  • bob_test: Contains the launch file for running the driving functions of bob.
  • bob_pid: Contains configuration files for the lateral controller used in assisted driving.

Note: Folder structure reference

Coding Guidelines

  • Write a good function description at the top

  • Structure the Code in a logical flow

    • Not too many blank lines

  • Use logical variable names

    • Use _ for separating words

  • Explaining every major step by short comments

  • Don't use global namespaces

  • Avoid long functions

    • Keep it as simple as possible
    • Using acronyms for too long words is ok

Formatting

We are using several formatting programs for the different languages. All of them are available in the Extensions of VS Code. The following steps guides you threw the Installation for each of them and the Setting for the automatically format on save.

C++

  • Open VS Code and go to the Extensions
  • Search for C/C++
  • Choose the first one in the List and click install

Python

  • Open VS Code and go to the Extensions
  • Search for Black Formatter
  • Choose the first one in the List and click install

Yaml and all other Languages

  • Open VS Code and go to the Extensions
  • Search for Prettier - Code formatter
  • Choose the first one in the List and click install

Setting for Format on Save

  • Open the Settings by pressing Ctrl + ,
  • Search for Editor: Format on Save
    • Make sure that the option is checked
  • Now, when you installed all formatter, each code will be formatting automatically when you save the file

Hardware Documentation

  • Diagrams/Pictures of circuits
  • Explanation of which hardware is being used and links to documentation

Developer Documentation

  • Software Design Description (SDD)

    • Contains the software design and architecture

  • Source Code Documentation

    • Comments in code which should be readable and comprehensible

  • Feature guides

    • Description on how to run a given feature on the robot
    • Test script which shows feature working
    • For complex feature, flow diagrams and other diagrams should be used to break the problem down

User Documentation

  • User manual

    • Where users can go if they have issues or want explore advance features
    • Should have an easy to follow format
    • Logically organized
    • Searchable
    • Use simple language
    • Uses good visuals
    • Provides links to relevant sources
    • Details about minimum hardware requirements

  • How to guides

    • Showing how to do specific tasks when it comes to installation and other specific tasks
    • Can be in video format

  • Quick start guide

    • Guide to set up and start as quick as possible

  • Configuration guides

    • Contains how to adjust available settings

  • FAQ

    • Common problems or questions asked