search

BadRobots1014 / BadRobot2022

The code base for FRC Team 1014's 2022 (RAPID REACT) robot
Other
1 stars 0 forks source link

Document project structure and general control flow #7

Open wxb1ank opened 2 years ago

wxb1ank commented 2 years ago

Our code is fairly well-documented at the moment, but the file structure and 'bigger picture' ideas are not; I think it would be beneficial both for ourselves in the present and the programming team in the future to document these aspects. It might look like the following:

File Structure (/src/main/java/frc/robot/)

commands/

Autonomous and teleop. command implementations.

commands/drive/

'Drive strategy' implementations. These are not quite commands themselves; see DriveStrategyCommand.

prototype/

(...and so on.)

Control Flow

  1. Main::main
  2. Robot::new
  3. Robot::robotInit
  4. RobotContainer::new

When (shoot button) is Pressed

  1. The gatherer motor engages to collect cargo.
  2. (...and so on.)

(...and so on. I'd either list major methods or describe the control flow in prose. You might also consider using LaTeX to generate a directed graph.)

While our file structure probably follows WPILib conventions, and the control flow can probably be surmised from reading enough WPILib documentation, it would be very convenient to centralize this information in our actual codebase.

vchen04 commented 2 years ago

A convenient place to summarize the big-picture structure of the codebase is in a README.md at the root of the repository or on a repository wiki page.

wxb1ank commented 2 years ago

I agree; either of those would be great places for documentation/project overview. Maybe we could start with a README and flesh it out into a wiki if necessary.

We should also definitely include a "Troubleshooting" or "FAQs" section where we document the many "gotchas" we were bitten by this year. Some I can think of include:

  1. Not fully resetting state in either Command::initialize or Command::exit—this caused our PID controller setpoints to not be reset after disabling the robot from the driver station, which in turn caused the robot to jerk violently upon re-enable;
  2. Not resetting PID controllers—this also caused the robot to jerk violently upon re-enable; and
  3. Relying on gyro displacement—it's really as inaccurate as the docs say.