Formatting Guide

Formatting Guide

Note: This guide assumes you've read Dependency Injection and have a solid understanding of Java

Formatting and code style is a very important part of programming, especially keeping a consistent style across a potentially large codebase spread across multiple users, like robot code. Accordingly, Riviera Robotics has a number of style choices which we choose to abide by in order to make our code more readable, perform optimally, and be easy to modify. For the most part, we follow the Google and Oracle Java conventions, but have some changes and additions. The check task will catch all mistakes and fail if there are any, but it's better to code with correct formatting the first time.

Curly Brackets

Curly braces/brackets are used as delimiters in Java, and denote the beginning and end of a block. Curly brackets must be paired to pass compile, but in terms of style they must be on the same line as a header if starting a block. End curly braces must be on separate lines. Two examples of this are given below:

// Correct
public class Example {
}

// Incorrect
public class Example
{
}

// Correct
public class Example {
    public Example() {
    }

    public void build() {
    }
}

// Incorrect
public class Example
{ // Do not put open curly brackets on new lines
    public Example()
    { // Do not put open curly brackets on new lines
    }

    public void build()
    {
}} // End curly brackets should not be on the same line

Indentation

Indentation in Java does not result in any difference in compile time or quality, but it is best practice to use correct indentation standards. Riviera Robotics currently uses four-space indenting, though IntelliJ automatically converts from the tab character to four spaces. Single four-space indents should be present on each class, constructor, loop, conditional, and method body, and return to the previous spacing at the end of the respective block.

// Correct
public class Example {
    public Example() {
    }

    public void build() {
    }
}

// Incorrect
public class Example {
        // Too many spaces on class indentation
        public Example() {
            build();
        }

// No class indentation
public void build() {
// No method indentation
System.out.println("built!");
}
}

Variables

Visibility

All variables should be private or protected. Try to use getter and setter methods if public access to a variable is needed. All variables passed through parameters that do not need to be modified (ex Subsystems) should be declared final.

Always put a space on each side of any assignment operator (read: =).

Do not use single-line multi-variable declarations.

Variables passed through a parameter directly to a field should be assigned to a field of the same name, when possible. This is more of a suggestion, but helps sometimes. Don't forget to use the this keyword to assign variables correctly.

// Correct
public class Example {
    private final DriveTrain driveTrain;

    public Example(DriveTrain driveTrain) {
        this.driveTrain = driveTrain;
    }

    pubic DriveTrain getDriveTrain() {
        return driveTrain;
    }
}

// Incorrect
public class Example {
    private final DriveTrain driveTrain;

    public Example(DriveTrain dt) {
        // Recommended: use the same name with the "this" keyword
        driveTrain = dt;
    }

    pubic DriveTrain getDriveTrain() {
        return driveTrain;
    }
}

// Incorrect
public class Example {
    // Fields should not be public and be annotated final (given Subsystem)
    public DriveTrain driveTrain;

    public Example(DriveTrain dt) {
        // Recommended: use the same name with the "this" keyword
        driveTrain = dt;
    }
}

If a variable is static and final, it should be named in CONSTANT_CASE. If not, variables should be named using lowerCamelCase.

private static final double SAMPLE_VALUE = 50.0; // Correct
public static final double SAMPLE_VALUE = 50.0; // Correct
private static double SAMPLE_VALUE = 50.0; // Incorrect
private static double sampleValue = 50.0; // Correct
private final double samplevalue = 50.0; // Correct
private double SAMPLE_VALUE = 50.0; // Incorrect
private double sampleValue = 50.0; // Correct

Classes

Classes should be named in CamelCase. Numbers are allowed. Length should be kept to a minimum, but the names should have a structure or otherwise have value as identifiers of the class's function. Abbreviations creating multiple uppercase letters in a row (ex RRSubsystem) are also allowed to keep length to a minimum.

Always put a space between the close parentheses on method headers and constructors (or the class name on class headers) and the open curly bracket.

Methods follow the same guidelines as classes, but should be written in lowerCamelCase. Names may infer the class context (e.g. turretSetAngle() could be setAngle() if in a class called TurretCommands)

Enums should be named in CONSTANT_CASE and have a newline for each enum. Additional newlines are acceptable. You do not need to include a () after each enum if there are no parameters to pass. Semicolon at the end of a no-param enum list is optional if not required by the compiler.

// Correct
public enum Example {
    LEFT,
    RIGHT
}

// Correct
public enum Example {
    LEFT(0),
    RIGHT(1);

    Example(int value) {
    }
}

// Incorrect
public enum Example {
    // Use CONSTANT_CASE naming scheme
    // Recommendation: put each enum on a new line
    left, right
}

Spacing

Conditionals

If statements should contain a space between if and the open parentheses, as well as a space between the close parentheses and the open curly bracket. All comparison operators (read: non-assignment operators) should have a space before and after them.

// Correct
if (value == 420) {
}

// Incorrect
if (value==420) {
    // Spaces needed around operators
}

// Incorrect
if(value == 420) {
    // Space needed before open parentheses
}

// Incorrect
if (value == 420){
    // Space needed after close parentheses
}

It is fine to omit a comparison operator when operating on a condition that is already a boolean value.

// Correct
if (boolValue) {
}

// Correct
if (boolValue == true) {
}

Loops

For loops should contain the same spaces as an if, with some more. The condition and increment parts of the "header" should have a space between the preceding semicolon and start of expression.

// Correct
for (int i = 0; i < 420; i++) {
}

// Incorrect
for (int i=0; i<420; i++) {
    // Spaces needed between operators
}

// Incorrect
for (int i = 0;i < 420;i++) {
    // Spaces needed after semicolons
}

Packages

Packages are always lowercase, and come with the root package org.rivierarobotics. A template for packages may be: commands, inject, robot, subsystems, util.

General Practices

• Always use the @Override annotation when overriding OR implementing a method.
• Don't ignore exceptions, they will crash the robot when thrown!
• Use array declarations String[] args, not String args[]