Open wxb1ank opened 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.
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:
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;
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
Main::main
Robot::new
Robot::robotInit
RobotContainer::new
When (shoot button) is Pressed
(...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.