Programming Norms
Last updated
Last updated
This is a list of norms and standards for how we handle our code—for example, how we like to handle parentheses, variable names, etc.
If not otherwise specified on this page, default to the Google Java Style Guide:
To enforce and auto-apply that style (along with some other basic style conventions), we use Spotless (https://github.com/diffplug/spotless) with the following configuration (https://github.com/frc937/robot2023/blob/cowtown2023/build.gradle):
IMPORTANT: If you are using git on Windows, make sure that git is set to checkout LF (Unix-style) line endings AND VS Code is set to LF (Unix-style) line endings. Otherwise, Spotless, VS Code, and git will all fight with each other over the line endings and you will be in line-ending purgatory for all eternity.
We also use the VS Code plugin for Spotless (https://marketplace.visualstudio.com/items?itemName=richardwillis.vscode-spotless-gradle) with the following configuration (https://github.com/frc937/robot2023/blob/cowtown2023/.vscode/settings.json) for linting and format-on-save:
We use GitHub Actions for compile CI/CD. Since tests and formatting checks are handled by Gradle, this will also run those. We use the following workflow file:
All of our code is hosted on our GitHub (https://github.com/frc937). All team members should be granted access to this organization on their own individual GitHub accounts, and they should work on code only on those accounts on their own separate devices. (git and GitHub will work on school computers, it just requires some extra legwork).
The robot code for each year should be contained in a GitHub repository owned by the frc937 organization called robot(year)
, where (year)
is the year of the season the robot is for. For example, our 2024 robot's repository would be called robot2024
. The WPILib project should share its name with the GitHub repository.
Additional repositories can (of course) be created for additional projects.
Each year's robot code should be initialized with the skeleton command-based framework from WPILib and our Spotless and GitHub Actions configurations (found above).
The general programming workflow should be as follows:
Identify necessary features and bugfixes
Assign team members to implement those features and bugfixes
Team members create topic branches off of main within the frc937/robot(year) repository for each feature/bugfix they implement
Team members create a pull request for each feature/bugfix once it is complete
At least one reviewer reviews and approves each PR
PR is merged into main
Rinse and repeat until the robot is ready!
A team of approved reviewers should be created for the programming team every year. Each PR must be approved by at least one reviewer before it can be merged into main, and reviewers may not approve their own PRs.
Reviewers should generally be experienced programmers, and should specifically be experienced with programming on Team 937. Most (if not all) lead programming specialists will be reviewers, but the team of reviewers is not necessarily limited to lead programming specialists.
If a reviewer is uncertain about a PR, they may defer to another reviewer for a second opinion. If no reviewer is confident about merging a PR and/or giving feedback before a merge, they may defer to a programming mentor.
ALL class names should be in PascalCase
Commands should start with an action verb
Example: DriveRobotOriented, ClimbUp, etc.
Should of course be descriptive
Should be descriptive of the subsystem it works with
Should be brief and begin with a noun
Example: Drive, Climber, Flywheel, etc.
Coordinate with mechanical and electrical to determine a common name for the subsystem
Example: If mechanical is calling a certain wheel the "index wheel," programming should call it that too
Should be descriptive
Most of these will be created for you by WPILib. If you have very many classes that are neither commands nor subsystems, you are probably doing something wrong.
All variable names should be in camelCase
Should, of course, be descriptive
Use this
If you have a formal parameter which sets an instance variable and it makes sense to name them the same thing, use parameterAndVariableName = this.parameterAndVariableName
Constants
Should be in ALL_UPPER_CASE
Constants should all be contained within the constants file, and referenced from that file throughout the project
When saying the name of something that has "init" in it, you must say it in a British accent (preferably a terrible one).