The Basics

// int — whole numbers only, no decimals
// use it for things that are always a whole number: motor IDs, counts, encoder ticks
int motorID = 5;

// double — decimal numbers (very precise, 64-bit)
// use it for speeds, distances, angles — anything that can be a fraction
double motorSpeed = 0.75;

// boolean — only two possible values: true or false
// use it for on/off states, flags, "did this happen?"
boolean isRunning = false;

// String — a piece of text (note the capital S — it's special)
// use it for labels, log messages, display names
String subsystemName = "Drivetrain";

// shooter subsystem variables
int     topMotorID     = 7;      // the unique number that identifies this motor on the robot's wiring system
int     bottomMotorID  = 8;      // same idea — unique ID for the bottom flywheel motor on the CAN bus
double  targetSpeed    = 0.85;   // desired flywheel speed (0.0 to 1.0)
boolean isAtSpeed      = false;  // whether shooter has reached target speed
String  subsystemName  = "Shooter"; // used for logging and dashboard display

// regular variable — can be changed later
double motorSpeed = 0.5;
motorSpeed = 0.8;  // totally fine, reassignment is allowed

// constant — can NEVER be reassigned after this line
final int kMotorID = 5;
kMotorID = 6;  // COMPILE ERROR: cannot assign a value to final variable kMotorID

// in robot code, constants live in Constants.java and look like this:
public static final int    kShooterMotorID  = 7;
public static final double kMaxSpeed_mps    = 4.5;   // meters per second
public static final double kGearRatio        = 8.46;  // motor turns per wheel turn

public class ShooterSubsystem {

    // instance variables — these get default values automatically
    private int     m_motorID;    // defaults to 0
    private double  m_speed;      // defaults to 0.0
    private boolean m_isRunning;  // defaults to false
    private String  m_name;       // defaults to null (nothing)

    public void someMethod() {
        // local variable — NO default, must assign before using
        int speed;
        System.out.println(speed); // COMPILE ERROR: variable speed might not have been initialized

        // fix: assign it first, then use it
        int fixedSpeed = 0;
        System.out.println(fixedSpeed); // works fine, prints: 0
    }
}

// + addition — adds two values
double total = 3.0 + 1.5;   // total = 4.5

// - subtraction — subtracts second from first
double diff = 5.0 - 2.0;    // diff = 3.0

// * multiplication — multiplies two values
double product = 4.0 * 2.5; // product = 10.0

// / division — divides first by second (CAREFUL with ints! see below)
double quotient = 9.0 / 4.0; // quotient = 2.25

// % modulo — gives you the REMAINDER after division
int remainder = 7 % 3;       // 7 ÷ 3 = 2, with 1 left over. so remainder = 1

// classic FRC bug: encoder math with integer division
int ticks       = 1500;
int ticksPerRev = 2048;
int revs        = ticks / ticksPerRev; // you think this is ~0.73 right? WRONG
                                        // it's 0. the 0.73 is silently thrown away.

// ─────────────────────────────────────────
// Fix 1: cast one of the ints to double first
double revsFixed = (double) ticks / ticksPerRev; // 0.732... correct!!

// Fix 2: use a double literal (the .0 forces Java to use double math)
double revsFixed2 = 1500.0 / ticksPerRev;          // also 0.732... correct!!

// Fix 3: declare both as double from the start if you need decimals
double dTicks       = 1500.0;
double dTicksPerRev = 2048.0;
double revsFixed3   = dTicks / dTicksPerRev; // 0.732... correct!!

// basic examples
int a = 10 % 3;  // 10 ÷ 3 = 3 remainder 1 → a = 1
int b = 12 % 4;  // 12 ÷ 4 = 3 remainder 0 → b = 0 (divides evenly)
int c = 7 % 10; // 7 ÷ 10 = 0 remainder 7 → c = 7 (smaller ÷ bigger = smaller)

// FRC use case: cycle through an array of 4 autos
int index = 0;
index = (index + 1) % 4; // 0→1→2→3→0→1→2→3... wraps around forever

double speed = 0.5;

// long way vs shorthand — they're exactly the same thing
speed = speed + 0.1;  // speed is now 0.6
speed += 0.1;         // speed is now 0.7 — shorthand for speed = speed + 0.1

speed -= 0.2;         // speed is now 0.5 — shorthand for speed = speed - 0.2
speed *= 2.0;         // speed is now 1.0 — shorthand for speed = speed * 2.0
speed /= 4.0;         // speed is now 0.25 — shorthand for speed = speed / 4.0

// ++ and -- add or subtract exactly 1
int count = 0;
count++;  // count is now 1 — shorthand for count = count + 1
count++;  // count is now 2
count--;  // count is now 1 — shorthand for count = count - 1

int speed = 80;

boolean r1 = speed == 80;  // true  — is speed EQUAL to 80?
boolean r2 = speed != 80;  // false — is speed NOT EQUAL to 80?
boolean r3 = speed > 50;   // true  — is speed GREATER THAN 50?
boolean r4 = speed < 100;  // true  — is speed LESS THAN 100?
boolean r5 = speed >= 80;  // true  — greater than OR equal to?
boolean r6 = speed <= 79;  // false — less than or equal to 79?

int a = 2 + 3 * 4;      // 14, not 20 — multiplication happens first
int b = (2 + 3) * 4;    // 20 — parentheses force addition to go first

// FRC example: velocity conversion with explicit parentheses
// (much easier to read and verify than a long unseparated expression)
double kWheelCircumference_ft = Math.PI * (4.0 / 12.0); // 4-inch radius in feet
double speed_fps = encoderRate * (1.0 / 2048) * 10 * kWheelCircumference_ft;

public void periodic() {
    // 'speed' is declared here — it lives for the WHOLE method
    double speed = 0.5;

    if (isButtonPressed) {
        // 'boost' is declared inside this if block
        // it ONLY exists inside these curly braces
        double boost = 0.2;
        speed += boost;  // fine — both 'speed' and 'boost' exist here
    }
    // 'boost' is GONE here — the if block ended, boost died with it
    // trying to use boost here would be a compile error: cannot find symbol

    setMotor(speed);  // 'speed' is still alive — it was declared in this method scope
}

public void runShooter(double requestedSpeed) {
    // method scope — visible to everything below in this method
    double safeSpeed = Math.min(requestedSpeed, 1.0);

    if (safeSpeed > 0.1) {
        // if-block scope — 'clampedOutput' only lives in here
        double clampedOutput = safeSpeed * 0.9;  // 10% safety margin
        m_motor.set(clampedOutput);  // fine — clampedOutput exists here

        // this inner scope can see 'safeSpeed' from the outer scope ✓
        System.out.println("Running at: " + safeSpeed);
    }
    // clampedOutput is gone — can't use it here
    // safeSpeed is still alive — use it freely
}

public class ShooterSubsystem {

    // CLASS SCOPE — these are accessible from ANY method in ShooterSubsystem
    private double  m_targetSpeed = 0.0;
    private boolean m_isSpinning  = false;

    public void setSpeed(double speed) {
        // METHOD SCOPE — 'clampedSpeed' only lives inside setSpeed()
        double clampedSpeed = Math.min(speed, 1.0);
        m_targetSpeed = clampedSpeed;   // modifying the class-level variable ✓
        m_isSpinning = (clampedSpeed > 0.05); // reading AND writing class vars ✓
    }

    public double getSpeed() {
        // m_targetSpeed is accessible here too — it's class scope
        return m_targetSpeed;
        // clampedSpeed is NOT accessible here — it died when setSpeed() ended
    }
}

// BAD — cryptic garbage. no one knows what this does
double x1   = 0.8;
int    y     = 3;
boolean f   = true;

// GOOD — completely self-documenting
final double  kMaxShooterSpeed_mps = 0.8;  // k prefix + units in name!!
final int     kShooterMotorID       = 3;
boolean m_isShooterEnabled          = true;

// ── WIDENING — automatic, zero data lost ──────────────────────────
// int is 32 bits, double is 64 bits — int fits perfectly inside double
int ticks = 500;
double pos = ticks; // Java automatically converts: pos = 500.0
// no cast needed, no data lost — Java handles this silently

// ── NARROWING — must be EXPLICIT, data will be lost ───────────────
// double is 64 bits, int is 32 bits — the decimal part gets chopped
double reading = 3.87;
int truncated = (int) reading; // you must write (int) to say "yes i know i'm losing data"
                                // truncated = 3 — the .87 is GONE

// more examples of narrowing
double a = 9.99;   int ia = (int) a;  // ia = 9, NOT 10
double b = 1.01;   int ib = (int) b;  // ib = 1
double c = -2.8;  int ic = (int) c;  // ic = -2 (not -3 — truncates TOWARD ZERO)

// scenario 1: encoder math — need double result from int inputs
int    rawTicks     = 3072;
int    ticksPerRev  = 2048;
double revolutions  = (double) rawTicks / ticksPerRev; // cast first, then divide
// without the cast: 3072 / 2048 = 1 (integer division! wrong!)
// with the cast: 3072.0 / 2048 = 1.5 (correct)

// scenario 2: gear ratio math
final double kGearRatio = 8.46;
double motorRPM = 5400.0;
double wheelRPM = motorRPM / kGearRatio; // ~638.3 RPM
int    wheelRPM_approx = (int) wheelRPM;  // 638 — dropped the .3

// scenario 3: rounding properly (for display purposes)
double speed_mps = 3.7892;
int    rounded   = (int) Math.round(speed_mps); // 4 — actually rounds correctly

// ── Number → String (for display and logging) ─────────────────────
double speed = 0.75;

// method 1: string concatenation — easiest
String label1 = "Speed: " + speed;           // "Speed: 0.75"

// method 2: String.format — gives you control over decimal places
String label2 = String.format("%.2f m/s", speed); // "0.75 m/s" (2 decimal places)
String label3 = String.format("%.0f RPM", 638.3); // "638 RPM" (0 decimal places)

// method 3: Integer.toString / Double.toString
String idStr  = Integer.toString(7);              // "7"

// ── String → Number (parsing config, reading sensor text) ─────────
String raw = "42";
int    parsed1 = Integer.parseInt(raw);           // 42
double parsed2 = Double.parseDouble("3.14");       // 3.14

// ── Type 1: Single-line comment ───────────────────────────────────
// everything after // on this line is ignored by the compiler
// use for: quick explanations of a single line, inline notes
double speed = 0.5; // starting speed — will be adjusted by driver input

/*
 * ── Type 2: Block comment ─────────────────────────────────────────
 * spans multiple lines.
 * use for: explaining a big section of code, temporarily disabling
 * a chunk during debugging (just wrap it in these and it's gone)
 *
 * this entire block is ignored by the compiler
 */

/**
 * ── Type 3: Javadoc comment ───────────────────────────────────────
 * this generates HTML documentation AND shows as hover tooltips in your IDE.
 * use above EVERY public class and EVERY public method.
 * the @param tag explains an input parameter.
 * the @return tag explains what the method gives back.
 *
 * @param speed the target motor speed, from -1.0 (full reverse) to 1.0 (full forward)
 * @return true if the motor successfully reached the target speed within tolerance
 */
public boolean setSpeed(double speed) {
    // implementation here...
    return true;
}

package frc.robot.subsystems;   // 1. package — tells Java where this file lives in the project
                                 //    always matches the folder path. always first line.

import edu.wpi.first.wpilibj2.command.SubsystemBase; // 2. imports — bring in other classes you need
import com.ctre.phoenix6.hardware.TalonFX;           // TalonFX = the motor controller our team uses (made by CTRE)

/** 3. Javadoc for the class — what does this subsystem do? */
public class ShooterSubsystem extends SubsystemBase {  // 3. class declaration
                                                          //    'extends SubsystemBase' = this is a WPILib (the Java library all FRC teams use for robot programming) subsystem

    // 4. fields (instance variables) — the "state" of this subsystem
    private final TalonFX m_motor;
    private double          m_targetSpeed = 0.0;

    // 5. constructor — runs once when the subsystem is created at robot startup
    public ShooterSubsystem() {
        m_motor = new TalonFX(7); // create the motor object on CAN ID 7
    }

    // 6. methods — what this subsystem can DO
    public void setSpeed(double speed) {
        m_targetSpeed = Math.min(speed, 1.0);
        m_motor.set(m_targetSpeed);
    }

    public double getSpeed() {
        return m_targetSpeed;
    }

} // end of class — NO semicolon after the closing brace!!

// WRONG — 'class' is a reserved keyword, can't use it as a variable name
int class = 5;  // COMPILE ERROR: 'class' is reserved by Java

// WRONG — 'Class' with capital C is totally different from 'class'
// Class (capital C) is an actual Java built-in type, unrelated to what you want

// WRONG — forgot semicolon on variable declaration
int motorID = 5   // COMPILE ERROR: ';' expected

// WRONG — semicolon where it doesn't belong
if (speed > 0.5); {  // this compiles but does something totally wrong!!
    m_motor.set(speed);
}

// CORRECT
int    myClass    = 5;
String className  = "Shooter";
if (speed > 0.5) {
    m_motor.set(speed);
}