Git

Accounts

Please commit with your own git account!
Yes, sometimes it's convenient to throw together commits on the driver station account and push, but that can cause problems when trying to find credit/blame. It is important that all commits are authored by the correct account.

Pull Requests

Pull request names must start with either Feature: or Fix: and should summarize the changes. Do not make names too long; they should generally be no longer than 10 words. Feature PR names should usually be similar to the names of the branches. Fix names are more complex. Bugfix branches should be named after the problem that is being solved, but fix PRs should describe where the problem originated. For example, there could be a feature branch named add-arm-sim, which got merged to dev from a pull request named Feature: Add Arm Sim. Later, people notice that the elevator sim isn't working properly, so they make a branch fix-elevator-sim. When the elevator sim is working properly again, they will make a pull request named Fix: Elevator Sim Regression from Arm Sim Addition. Even if a change is not a bugfix (i.e. removing an unnecessary file), it should still be labeled as a fix.

Branches

Branch names are important. They need to be short, readable, and describe what the point of the branch is. Branch names should not exceed 5 words, and should all follow kebab-case. This means that there should be no capital letters, and words should be separated by hyphens.

Commits

This answer from Stack Overflow describes commit best practice than I ever could:

1. Never deliberately make a commit that will leave the repository in a broken state, even if you intend to shortly make another that will fix it.
2. Prefer small commits to large commits. When tracking down the source of some issue by chopping through the repository, it is easier to track down the source of a problem if the steps are small; and it is easier to quickly understand the changes in a small commit.
3. Prefer a single commit for a single feature, fix or other logical unit of work; avoid "partial" commits that introduce changes that are not functional without further commits, and avoid compound commits that contain several unrelated changes. If you are making a stylistic change that does not change functionality, commit that separately. All this increases the likelihood of leaving the build unbroken, and makes it much easier for another person unpicking codebase issues to understand the sequence of functional changes that took place and to grasp each individual change quickly.
4. If you are working on a very complex feature or refactor that cannot be made safe or useful to commit while partially written, work on a private branch, commit to that often, try to stay up to date with trunk, and if at all possible, when finally merging to trunk, do so in a manner that leaves future maintainers a way to get at the private branch's history.

So, to sum up: always aim to make the smallest commit you can that is both necessary and sufficient to complete a single logical unit of work.

Following this makes commit names extremely simple, as each commit is naturally a small, easily summarizable change.

Code

We exclusively use Visual Studio Code (or derivatives) and the Language Support for Java(TM) by Red Hat extension for our language server. Do not use other IDEs or language servers.

Indentation and Line length

Ensure automatic styling is enabled in the settings for the Java LS It should be enabled by default as long as VS Code is utilizing .vscode/settings.json from the project root.

We use 4-space indents (DO NOT USE TAB CHARACTERS), and maximum 100 character lines.

Package names

Package names should be entirely lowercase. Keep them short (<20 characters), and don't be afraid to abbreviate. Do not separate words.

Class names

Class names should follow UpperCamelCase. They can be longer, but as a general rule of thumb, they shouldn't be a mouthful to say out loud. Never abbreviate a class name.

Methods/Functions

All methods/functions should follow camelCase casing. Do not abbreviate method/function names.

Variables

Do not use Hungarian Notation. This means do not prefix variables with information about their scope (member, argument, etc.) or about their type (double, char, etc.). This information should be obvious anyways. If the type or scope changes but you forget to update the name, the compiler won't catch the mismatch, which can lead to confusion or bugs.

If a class can be instantiated, mutable static variables are not allowed. The static keyword can only be used in combination with the final keyword to create a constant. All constants should follow the UPPER_SNAKE_CASE casing.

All other variables should follow camelCase casing. Do not abbreviate variable names.