Code Standards

Decatur Robotics Code Standards

Formatter XML URL

General

> Package statement goes before the import statements.
Put a blank line after the package statement.

> Import statements go at the top, after the package statement.
Import statements are placed at the top of the file, but after the package statement. If you have a lot of import statements, split the statements into groups, with a blank line in between each group.

> Perform all configurations in constructors.
Set all configurations for motors, sensors, etc. in the constructor. Configurations include current limits, motor following, motor inverting, neutral mode, voltage compensation, and anything else.

> Static classes should be entirely constant.
Ex: Config can be static, but ShooterSubsystem cannot.

> Make each method focus on one task.
If a method performs multiple separate tasks, separate it into a method for each task.
Example: Separate motor speed ramping and clamping into getRampedPower and getClampedPower methods.

> Opening braces { go on the same line as their control statements.
We use K&R style.
Example:

public class Example {

    private static void main(String[] args) {
        System.out.println("Hello, world!");
    }

}

> Each line should not have more than 100 characters.
If a single line of code or comment would have more than 100 characters, split it into multiple lines. For code, this does not mean splitting it into multiple statements; just add a line break.
Ex: if(LocalDateTime.now().compareTo(lastSwapTime.plusSeconds(Constants.AGITATOR_REVERSE_TIME)) == 1) { is 99 characters.

> Comments and naming must be in American English.
This includes you, Davis.

Naming

> Prioritize explanatory names over concise names.
Avoid abbreviations. It’s okay for names to be long. Longer names are better than unclear names. The only exception to this rule is when you're looping a certain amount of times in a for loop.

for (int i = 0; i < 10; i++) {} // <- This is okay!

private final int a = 21; // <- What is this supposed to be used for???
private final int addressibleLedPixels = 21; // <- This is much better!

> Variables use lower camelCase naming.
Variable names should be lowercase, except for the first letter of each word after the first. Acronyms are treated as a word.
Ex: leftMotor
Ex: Pid

> Types, enums, and enum values use upper camelcase naming.
Types (classes and interfaces), enums, and enum values should be lowercase, except for the first letter of each word.
Ex: ShooterSubsystem
Ex: ITeamTalon

> Methods use lower camelcase naming.
Methods use the same naming as variables
Ex: setMotorPowers

> Final primitives and enums should be all uppercase, with underscores between words.
Ex: GEAR_RATIO

> For final constants located in sub-constants files (ex. "ArmConstants.java"), they should NOT have the related system as part of their name.
Ex: "ARM_KP" should be instead just written as "KP"

> Final objects should use upper camelcase.
Ex: SwerveConfig

> Final classes are named the same as other classes.
Ex: Config is Config regardless of whether it’s final or not (it is).

> Interfaces should have an I at the start. Add an I to the start of the interface name, even if there is already an I at the start.
Ex: ITeamTalon
Ex: IIdentifier

> Classes use upper camelcase.
Ex: TankDrivetrainSubsytem

> File names match class names.
Ex: TankDrivetrainSubsystem

> Packages (folders) use all lowercase.
Ex: frc/lib/modules/tankdrivetrain

> Name motor variables with the sideSystemMotorPaired convention. Use the side of the robot the motor is on (left, right, front, back), the system it is a part of (shooter, drivetrain, elevator, etc.), the word “motor”, and whether or not the motor follows another motor (main if not following, sub if following).
Ex: leftShooterMotorMain
Ex: rightShooterMotorSub

> Name getters with the getVariable(type variable) convention. Use the word “get” followed by the name of the variable it is getting.
Ex: getSpeedMod()

> Getters should always take no arguments.
Yeah, Owen.

> Getters should always have a return type.
Ex: public double getSpeedMod()

> Name setters with the setVariable(type variable) convention. Use the word “set” followed by the name of the variable it is setting.
Ex: setSpeedMod(double speedMod)

> Setters should always take one argument.

> Setters should always have a return type of void.

> Name methods calculating a value with the calculateValue(type variable) convention. Use the word “calculate” followed by the name of the value it is calculating.
Ex: calculateRampedPower(double powerDesired, double powerCurrent)

> Type parameters in generic classes use upper camelcase, should be multiletter and must have T at the end. Type parameters must be descriptive and have an additional T at the end.
Ex: ElementT

Variables

> Variables are declared at the start of the class.
Variables are declared before methods.

> Use the minimum protection level, private, when public is not necessary.
Always use protection (in your code)! Use private whenever possible. Avoid public. If a variable is public, there must be a very good reason. If something only needs to be accessed within the same package, use no access modifiers.

> Use getters and setters for non-private and non-protected variables.
Instead of making a variable public, create getters and setters to control access. Do not make both if you do not need both. It is ok to have only a getter or only a setter.

> Name method parameters the same name as any variables being set to them.
Use the “this” keyword to reference class variables.

> Variables that are not compile-time constants should be set in a constructor.
If a variable is not a final primitive, it should be initialized in a constructor. Compile-time constants (final primitives) can be set in the declaration.

> Static variables should be declared before instance variables.

> Access modifiers are placed first.
Access modifiers (public, private, etc.) are placed before other keywords (static, final, etc.).

Indentation & Spacing

Nested statements should be indented one more than the statement they are nested in.

> Indents are tabs.
Remember to turn uncheck Insert Spaces in VSCode's prefrences, because it is on by default.

> Methods should have a blank line between them.

> Separate similar sections of code with a blank line.

> Separate especially significant sections of code with multiple blank lines.

> If you have multiple blank lines in a row, add a comment labeling the sections.
If a division is significant enough to warrant multiple blank lines, you must include a comment labeling the following section on the middle blank line.

> Classes should have a blank line at the start and at the end.
Classes should have a blank line after the declaration and before the contents of the class. These spaces are inside the class declaration.

> if, for, and while statements without squiggly brackets should be split into multiple lines.
The condition should be on a different line than the code to execute if the condition is true.
Ex:

if (Robot.isTest())
    motor.enable();

Comments & Annotations

> Use comments to explain what a block of code does and why we do it.
Ex: // This configures the motors to use their internal encoders
Ex: // Use internal encoders so we can have rotational sensing for the motor

> Use extensive comments!

> Don’t use excessive comments.
Single lines don’t need comments, and self-explanatory, simple pieces of code (setting a variable, addRequirements(), etc.) don’t need comments.

> Leave a space between the double-slash and your comment.
Ex: // Your comment

> For methods, annotations go on the line before the declaration. For variables, annotations go before the keywords.

> Use the @Override annotation on method overrides.
Put @Override on the line before the method declaration. This annotation should be added to execute(), end(), etc.

> Use multi-line comment style for comments longer than 2 lines.
2-line comments use double-slash (//).
Ex:

/*
This is a multi-line comment.
It has more than two lines.
Very cool!
*/

// This is a multi-line comment.
// But it only has two lines!

// This is a single-line comment. It has one line!

WPILib Specific

> Always put addRequirements() at the end of your command constructor.

Vision Specific

Ask Owen.

Scout Janssen Specific

Ask Theo.