Humanoid Software Design Guidelines

Owned by Bhavyansh Mishra
Last updated: Sept 29, 2022 by Duncan Calvert
2 min read

Software Development Requirements

Primary author for any class or file needs to add their signature and timestamp in a block comment clearly visible on the top. 

Subsequent authors that make major changes should add their names as secondary authors

Features should be approved to be merged at least by two other people. 

Ask for feature requests to be merged on the #humanoid-software-pull-requests channel. Feel free to bug people if they forget to review your branch. 

Spend a day to comment all your past code to a level that the code can be used by anyone else on the team in the future

Software Development Guidelines

Always Design before you Develop

Get the Design Review'ed before you start implementing any new feature that needs multiple files of code. Get feedback from people, and then incorporate that feedback into the design. 

Consider the Model - View - Controller (MVC) framework before designing (not even developing yet) any module that might require graphical user interface at some point.

Ensure there is no robot logic being performed in the same class as either the Viewer (the graphics framework specific UI class) or the controller (the class that owns the Viewer and the Model and orchestrates data transfers between them). 

The core logic should all be in the Model part of the module and agnostic of what graphics framework may be used to access inputs or present output results to the user. 

At least add one comment to explain any method that either goes over 10-20 lines of code, or performs a task that might not be intuitive to someone completely new to the code.

Archive the files that are intended to be never used again. 

Robotics is already convoluted enough. Provide as much information and documentation as possible about how your code works for the rest of the team. 

Software Development Sins

Duplication of code

Implementing GUI and Robot logic in the same class

Merging a feature branch without a properly reviewed Pull Request

Storing trash, misleading or unnecessary files in the repositories

Confusing or ambiguous file, class, method or variable names

Pull Requests

Pull Requests are useful for many reasons:

  • Bamboo will build your branch if it has an associated Pull Request.
  • It is easy to see the diffs of your branch. (Though you should know how to do this locally as well.)
  • You can discuss the code with inline comments.
  • You can add reviewers for several reasons:
    • To ask for review.
    • To show them how something works.
    • To teach them about how to implement new things.
    • To help avoid mistakes.

Should use the prefix "[WIP]" (Work In Progress) for PRs that are not intended to be merged yet. Removing this prefix will signal to reviewers that is it ready for review again.

We could instead try using "Needs Work" button for this.