Arrays & Methods

// tracking four motors with four separate variables — already painful
int motor1 = 1;
int motor2 = 2;
int motor3 = 3;
int motor4 = 4;

// now imagine trying to loop through them. you literally can't.
// imagine passing them all to a method. nightmare.
// imagine changing all four to a new base CAN ID. hunt and replace, four times.

// one variable, four values, perfectly loopable
int[] motorIDs = {1, 2, 3, 4};

// Way 1: declare the size, fill it in slot by slot
// Java fills all empty slots with 0 for int/double, false for boolean, null for objects
int[] arr = new int[4]; // creates 4 slots, all set to 0 right now
arr[0] = 10;           // assign slot 0
arr[1] = 11;           // assign slot 1
arr[2] = 12;           // assign slot 2
arr[3] = 13;           // assign slot 3

// Way 2: declare and fill in one shot — size is inferred from the list
int[]    motorIDs     = {10, 11, 12, 13};           // 4 ints
double[] moduleAngles = {0.0, 90.0, 180.0, 270.0}; // 4 doubles
boolean[] sensorStates = {false, false, true, false}; // 4 booleans

String[] modules = {"FL", "FR", "BL", "BR"};
//                    [0]    [1]    [2]    [3]
//               ↑ first                last ↑
//              (NOT 1!)           (NOT 4!)

System.out.println(modules[0]); // "FL" — index 0, the first element
System.out.println(modules[1]); // "FR" — index 1
System.out.println(modules[2]); // "BL" — index 2
System.out.println(modules[3]); // "BR" — index 3, the last element

// changing a value is the same syntax as reading, just with = on the right
modules[2] = "BackLeft"; // slot 2 now holds "BackLeft"

double[] speeds = {0.5, 0.75, 1.0, -0.5};

System.out.println(speeds.length); // 4 — counts total slots, not last index
// NOTE: last valid INDEX is 3, but LENGTH is 4. classic confusion point.

// .length in a for loop — this pattern is everywhere in FRC code
for (int i = 0; i < speeds.length; i++) {
    System.out.println("Speed at index " + i + ": " + speeds[i]);
}
// prints:
// Speed at index 0: 0.5
// Speed at index 1: 0.75
// Speed at index 2: 1.0
// Speed at index 3: -0.5

int[] motorIDs = {10, 11, 12, 13};
// valid indices: 0, 1, 2, 3

System.out.println(motorIDs[4]);  // CRASH — index 4 doesn't exist
System.out.println(motorIDs[-1]); // CRASH — negative indices are also invalid

// BAD loop that crashes — uses <= instead of <
for (int i = 0; i <= motorIDs.length; i++) { // on last loop: i=4, CRASH
    System.out.println(motorIDs[i]);
}

// GOOD loop — uses strictly less than (<)
for (int i = 0; i < motorIDs.length; i++) { // stops at i=3, perfectly safe
    System.out.println(motorIDs[i]);
}

// safely getting the last element
System.out.println(motorIDs[motorIDs.length - 1]); // 13 — always safe

final int[]    kModuleCANIDs    = {10, 11, 12, 13};
final double[] kModuleAngles_deg = {0.0, 90.0, 180.0, 270.0};

// both arrays have .length == 4, so this loop runs exactly 4 times (i = 0,1,2,3)
for (int i = 0; i < kModuleCANIDs.length; i++) {
    System.out.println(
        "Module " + i +
        ": CAN ID = " + kModuleCANIDs[i] +  // same index, different array
        ", offset angle = " + kModuleAngles_deg[i] + "°"
    );
}
// Module 0: CAN ID = 10, offset angle = 0.0°
// Module 1: CAN ID = 11, offset angle = 90.0°
// Module 2: CAN ID = 12, offset angle = 180.0°
// Module 3: CAN ID = 13, offset angle = 270.0°

// Place 1: in driveForward()
double wheelRPM1 = motorRPM1 / 8.46;

// Place 2: in driveRotate()
double wheelRPM2 = motorRPM2 / 8.46;

// Place 3: in getTelemetry()
double wheelRPM3 = motorRPM3 / 8.46;

// ...oops. the real gear ratio is 8.14, not 8.46.
// now you need to fix it in 3 places. miss one and your robot math is wrong.

// write the recipe once — fix gear ratio here, fixed everywhere
public static double calcWheelRPM(double motorRPM, double gearRatio) {
    return motorRPM / gearRatio;
}

// call it from anywhere, as many times as you want
double wheelRPM1 = calcWheelRPM(motorRPM1, 8.46);
double wheelRPM2 = calcWheelRPM(motorRPM2, 8.46);
double wheelRPM3 = calcWheelRPM(motorRPM3, 8.46);

//  [1]    [2]    [3]       [4]          [5]                    [5]
public static double calcWheelRPM(double motorRPM, double gearRatio) {
    return motorRPM / gearRatio; // [6] — the body, and return statement
} // closing brace ends the method

// void method — does something useful, returns nothing
public static void printSpeed(double speed) {
    System.out.println("Current speed: " + speed);
    // no return statement needed — Java auto-returns when the block ends
    // (you CAN write bare "return;" to exit early, but it's optional here)
}

// returning method — calculates something and hands the result back
public static double clampSpeed(double speed, double maxSpeed) {
    if (speed > maxSpeed)  return  maxSpeed; // early return if too high
    if (speed < -maxSpeed) return -maxSpeed; // early return if too low
    return speed;                             // already in range, return as-is
}

// calling them — notice the difference
printSpeed(0.75);                                 // called as a statement — no assignment
double safeSpeed = clampSpeed(1.5, 1.0); // safeSpeed = 1.0 (was clamped)
double alsoSafe  = clampSpeed(0.8, 1.0); // alsoSafe = 0.8 (already in range)

// step 1: a focused method that does one thing
public static double motorRPMtoWheelRPM(double motorRPM, double gearRatio) {
    return motorRPM / gearRatio;
}

// step 2: another focused method that does one thing
public static double wheelRPMtoSpeed_fps(double wheelRPM, double wheelDiam_in) {
    double circumference_ft = Math.PI * wheelDiam_in / 12.0; // convert inches to feet
    return wheelRPM * circumference_ft / 60.0;               // RPM to fps
}

// step 3: a higher-level method that calls both of the above
public static double motorRPMtoSpeed_fps(double motorRPM, double gearRatio, double wheelDiam_in) {
    double wheelRPM = motorRPMtoWheelRPM(motorRPM, gearRatio);   // call #1
    return wheelRPMtoSpeed_fps(wheelRPM, wheelDiam_in);           // call #2
    // reading this, you can understand what it does without seeing the math
}

// MISTAKE 1: forgetting the return statement
// compiler says: missing return statement
public static double addValues(double a, double b) {
    double result = a + b;
    // oops — computed result but never returned it
    // fix: add "return result;" here
}

// MISTAKE 2: return type doesn't match what you actually return
// compiler says: incompatible types: double cannot be converted to int
public static int getSpeed() {
    return 0.75; // 0.75 is a double, but signature says int — mismatch
    // fix: either change return type to double, or return (int) 0.75
}

// MISTAKE 3: calling with wrong argument types
// compiler says: method calcWheelRPM(double,double) not applicable for arguments (String,double)
public static double calcWheelRPM(double motorRPM, double gearRatio) {
    return motorRPM / gearRatio;
}
calcWheelRPM("5400", 8.46); // "5400" is a String — wrong type, compile error
// fix: pass the number as a number: calcWheelRPM(5400.0, 8.46)

public static double calc(double x, double y) {
    return x / y;
}

public static double conv(double a, double b, double c) {
    return a * Math.PI * b / 12.0 * c / 60.0;
}

// 1. Single-line comment — use for quick inline explanations
// starts with // and goes to the end of the line
// compiler completely ignores everything after //
double safeSpeed = Math.min(speed, 1.0); // clamp — TalonFX faults above 1.0

/*
 * 2. Block comment — spans multiple lines
 * use when you want to explain a whole section,
 * or temporarily disable a chunk of code during debugging
 * starts with slash-asterisk, ends with asterisk-slash
 */

/**
 * 3. Javadoc comment — this is the important one for team code
 * same as a block comment but with TWO asterisks to start
 * IDEs like VS Code and IntelliJ show this as a hover tooltip
 * place one directly above every public class and every public method
 *
 * @param speed  the target speed in range -1.0 to 1.0
 * @return       true if the motor reached the target speed
 */
public boolean setSpeed(double speed) {
    // implementation here...
    return true;
}

/**
 * Calculates wheel RPM from a motor's RPM and the drivetrain gear ratio.
 * Use this any time you need to convert raw motor velocity to actual wheel speed.
 * The gear ratio is defined as motor turns per wheel turn (e.g. 8.46 means
 * the motor spins 8.46 times for every 1 rotation of the wheel).
 *
 * @param motorRPM  the motor's rotational speed in RPM (Falcon 500 free speed: ~6380)
 * @param gearRatio motor turns per wheel turn — higher ratio = more torque, less speed
 * @return the resulting wheel speed in RPM as a double
 */
public static double motorRPMtoWheelRPM(double motorRPM, double gearRatio) {
    return motorRPM / gearRatio;
}

/**
 * Clamps a speed value to a safe operating range.
 * TalonFX motor controllers fault if commanded above 1.0 or below -1.0.
 * Always clamp before passing values to motor.set().
 *
 * @param speed    the raw speed to clamp (can be any double)
 * @param maxSpeed the maximum allowed magnitude, usually 1.0
 * @return speed clamped to the range [-maxSpeed, maxSpeed]
 */
public static double clampSpeed(double speed, double maxSpeed) {
    if (speed >  maxSpeed) return  maxSpeed;
    if (speed < -maxSpeed) return -maxSpeed;
    return speed;
}

/**
 * Utility class for swerve drivetrain calculations.
 * Contains static methods for converting between encoder ticks, RPM, and
 * real-world speeds and distances. All methods are stateless (no instance needed).
 *
 * Used by: DriveSubsystem, autonomous routines, telemetry dashboards (telemetry = real-time data from the robot displayed on the driver's dashboard).
 */
public class DriveCalculator {

    /**
     * Converts encoder ticks to wheel revolutions.
     * @param ticks       raw encoder tick count from TalonFX
     * @param ticksPerRev encoder ticks per full motor revolution (TalonFX = 2048)
     * @return total revolutions as a double
     */
    public static double ticksToRevolutions(int ticks, int ticksPerRev) {
        return (double) ticks / ticksPerRev; // cast to avoid integer division
    }
}

// BAD: tells me what I can already see. zero extra information.
double clamped = Math.min(speed, 1.0); // set clamped to min of speed and 1.0

// GOOD: tells me WHY — and includes the specific thing to watch out for
double clamped = Math.min(speed, 1.0); // clamp — TalonFX faults above 1.0


// BAD: the number 8.46 is magic — where did it come from? when does it change?
double wheelRPM = motorRPM / 8.46;

// GOOD: the constant is named and the comment explains the physical meaning
final double kGearRatio = 8.46; // L2 SDS MK4i gear ratio (motor turns per wheel turn)
double wheelRPM = motorRPM / kGearRatio;


// BAD: vague javadoc that adds nothing — you could have just read the signature
/**
 * calculates rpm
 * @param a the a
 * @param b the b
 * @return something
 */

// GOOD: specific enough that a teammate understands without reading the body
/**
 * Converts motor RPM to actual wheel surface speed in feet per second.
 * Uses wheel circumference (pi * diameter / 12 for inches to feet) and
 * divides by 60 to convert from per-minute to per-second.
 *
 * @param wheelRPM     wheel rotational speed in RPM (after gear reduction)
 * @param wheelDiam_in wheel outer diameter in inches (e.g. 4.0 for 4" wheels)
 * @return surface speed in feet per second
 */