In the title, concisely what you aimed to change, in the future-tense.
Put more specific details in the commit description if needed.
Try not to write anything that can easily be seen with the changes.
Here are some examples of good commits:
If you move LimelightHelpers.java into the utils folder:
Reorganize LimelightHelpers.java properly
If you make a new "shooter branch"
Split Shooter subsystem and command from Master
Removed import references and usage in RobotContainer.java
Try to avoid deleting any important information. If you have doubts and aren't COMPLETELY SURE on deleting it, comment it out. It may be used later.
You should definitely delete:
Unused Imports (should be underlined in yellow in VSCode)
Completely dead & unnecessary code
Code that has been deprecated for something else, or just isn't going to be used anymore
Multiple assignments for single button (unintended assignment conflicts)
Delete if you get 2 - 3 second opinions from other people, or 1 second opinion and approval from sub-lead before deleting. Second opinions cannot be unsure, ask someone else if they are.
Comments are not meant to explain HOW code works, but are meant to explain WHY we are writing it or WHAT we aim to do in the long term. If you're unsure if your code is commented enough, ask someone who hasn't worked on the code to see if they can explain how the code will affect the output (not exactly every single step, but the whole section as a whole)
Javadocs are meant to document the code, so that it is easy to read for any other people who haven't written it. We will want to javadoc every single class and method written, so we can easily use the functions efficiently without asking around. To see any good examples, hover your mouse over any built-in functions in wpilib using VSCode (viewing its source if needed). Generally, we won't use any "See Also:" sections, so ignore them.
When writing javadocs, document absolutely everything about it. It's parameters, return value, required subsystems, and all other important information should be included. Information on how it works (such as any math, which should be comments in the method) should not be added, only on what it does to mutate the parameters, and how it uses them.
Name of class/ method
Description of what the method/class does.
All @params and description of what that they are
Every command that passes in a subsystem must have add requirements.
We want our names to be consistent, as we can make small "codes" on what each styling means, for example:
Constants should be in the UPPER_SNAKE_CASE format.
Local Scope variables should be camelCased.
Classes and methods should be PascalCased.
Privates should have the “m_” prefix
Variables must be named accurately to what the variable holds.
These styling changes should allow us to easily see if a variable is private, constant, or what it actually is without having to sift through the source code.
Generic
Subsystems created as final at the top
Unless commands are used in more than one place, create them where used
All default command initialization happens in the default configure bindings function
Constants
Variables
Constructor
Initialize
Execute
Is Finished
End
Constants
Variables
Constructor
Methods