OOP - Classes & Objects

// "public class Motor" — this is the CLASS DECLARATION
// "public"  = anyone anywhere in the project can use this class
// "class"   = this keyword tells Java this is a class definition (not an interface, not an enum)
// "Motor"   = the name of the class (always PascalCase — capitalize first letter of every word)
public class Motor {

    // FIELDS (instance variables) — the data each Motor object stores
    // declared inside the class but outside any method
    // every Motor object you create gets its OWN copy of these three values
    // "private" = only code written inside Motor.java can access these directly
    private int     m_id;          // CAN ID — the unique number identifying this motor on the robot's wiring system
    private double  m_speed;       // current speed (-1.0 to 1.0)
    private boolean m_isInverted;  // whether positive speed means backward

    // CONSTRUCTOR — runs automatically when you write "new Motor(...)"
    // three rules: same name as the class (Motor), no return type (NOT void), set initial state
    public Motor(int id, boolean isInverted) {
        m_id         = id;           // save the port number
        m_isInverted = isInverted;   // save whether it needs to be flipped
        m_speed      = 0.0;         // always starts at rest — never spinning on creation
    }

    // METHODS — what this Motor can do, and what info it can give you
    // instance methods belong to a specific object and can access its fields
    public void setSpeed(double speed) {
        // apply inversion: if this motor is inverted, negate the speed
        // this is why the left and right drivetrain motors spin correctly
        // even though they're physically facing opposite directions
        m_speed = m_isInverted ? -speed : speed;
    }

    public double getSpeed() {
        return m_speed;  // give back the current speed so other code can read it
    }
}

// "new Motor(1, false)" — creates a brand new Motor object in memory
// Java allocates space for it, runs the constructor, returns a reference to it
// leftMotor and rightMotor are TWO COMPLETELY SEPARATE objects
// they happen to be the same "type" (Motor) but they are different things
Motor leftMotor  = new Motor(1, false);  // port 1, not inverted
Motor rightMotor = new Motor(2, true);   // port 2, INVERTED (right side of drive)

// dot notation: call methods ON a specific object
// leftMotor.setSpeed(0.5) means "run setSpeed on the leftMotor object specifically"
leftMotor.setSpeed(0.5);
rightMotor.setSpeed(0.5);

// rightMotor is INVERTED, so 0.5 becomes -0.5 — they spin in opposite directions
// this is exactly how a real tank drive (tank drive = the simple drivetrain style where left stick controls left wheels, right stick controls right wheels) works on an FRC robot!!
System.out.println(leftMotor.getSpeed());  //  0.5
System.out.println(rightMotor.getSpeed()); // -0.5

// NOW: prove independence by stopping leftMotor only
leftMotor.setSpeed(0.0);

// leftMotor is stopped. rightMotor is COMPLETELY UNAFFECTED.
// they are separate objects with separate copies of m_speed
System.out.println(leftMotor.getSpeed());  // 0.0 — stopped
System.out.println(rightMotor.getSpeed()); // -0.5 — still going!!

// BAD — declared the variable but never created the object
// leftMotor is null right now — it doesn't point to anything
Motor leftMotor;
// or even worse — explicitly assigned null:
Motor leftMotor = null;

// now you try to use it...
leftMotor.setSpeed(0.5); // CRASH: NullPointerException at runtime!!
                           // "you can't call a method on nothing"

// ─────────────────────────────────────────
// GOOD — actually create the object with new
Motor leftMotor = new Motor(1, false); // now it points to a real Motor object
leftMotor.setSpeed(0.5);              // works perfectly

public class Motor {

    // FIELDS — declared at class level, outside any method
    // "private" = only Motor's own methods can touch these
    // "m_" prefix = WRT convention: m stands for "member variable"
    //   this makes fields visually distinct from local variables at a glance
    //   when you see m_speed in a method, you immediately know: that's a field
    private int     m_motorID;    // CAN ID — the unique number identifying this motor on the robot's wiring system
    private double  m_speed;      // current commanded speed (-1.0 to 1.0)
    private boolean m_isRunning;  // whether the motor is actively spinning

    // ... constructor and methods go below
}

public class Motor {

    private int     m_motorID;
    private double  m_speed;
    private boolean m_isRunning;

    // VALID CONSTRUCTOR — same name as class, no return type
    // Java calls this automatically when you write new Motor(5)
    public Motor(int motorID) {
        m_motorID  = motorID;  // set initial state here
        m_speed    = 0.0;     // always starts stopped
        m_isRunning = false;  // always starts not running
    }

    // INVALID — has "void" before the name
    // Java does NOT treat this as a constructor!! it's just a regular method
    // calling new Motor(5) would NOT call this — your fields would stay at defaults
    // public void Motor(int motorID) { ... }  <-- do NOT do this

    // INVALID — wrong capitalization (Java is case-sensitive)
    // "motor" != "Motor" — this is also just a regular method
    // public motor(int motorID) { ... }  <-- also wrong
}

public class Motor {

    private int m_motorID;

    // what if the parameter name exactly matches the field name?
    // Java has to pick ONE — it picks the local one (the parameter)
    // so "motorID = motorID" assigns the parameter to itself, doing nothing
    // m_motorID stays 0. the bug is SILENT — no error, wrong behavior forever
    public Motor(int motorID) {
        motorID = motorID; // BUG: assigns parameter to itself, field never set!!
    }
}

public class Motor {

    private int     m_motorID;
    private double  m_speed;
    private boolean m_isInverted;

    public Motor(int motorID, boolean isInverted) {
        // "this.m_motorID" = the field on THIS specific object (what we want to set)
        // "motorID"        = the parameter that was passed in (the new value)
        // left side is the destination, right side is the source — just like any assignment
        this.m_motorID   = motorID;    // field = parameter: correct!!
        this.m_isInverted = isInverted;
        this.m_speed      = 0.0;      // no conflict here but using this for clarity
    }
}

// BUGGY VERSION — field is never actually set
public class Motor {
    private int motorID;  // no m_ prefix (this sets up the name clash)

    public Motor(int motorID) {
        motorID = motorID;  // assigns the parameter to itself. field stays 0.
    }

    public int getID() { return motorID; }
}

Motor m = new Motor(5);
System.out.println(m.getID()); // prints: 0 ... NOT 5. silent bug!!

// ─────────────────────────────────────────
// FIXED VERSION — use m_ prefix to prevent the name clash
public class Motor {
    private int m_motorID;  // m_ prefix = field, different name from parameter

    public Motor(int motorID) {
        m_motorID = motorID;  // unambiguous: left is field, right is parameter
    }

    public int getID() { return m_motorID; }
}

Motor m = new Motor(5);
System.out.println(m.getID()); // prints: 5 — correct!!

// BAD — public field, anyone can bypass your logic and write garbage values
public class DangerousMotor {
    public double speed; // no protection at all!!
}

// anywhere in the project, someone can do this:
DangerousMotor m = new DangerousMotor();
m.speed = 9999.0; // compiles fine. no error. your motor is cooked.
m.speed = -500.0; // also fine. also bad.
m.speed = Double.NaN; // Java lets you. hardware does not appreciate this.

// ─────────────────────────────────────────────────────────────
// GOOD — private field with a setter that validates input
public class SafeMotor {
    private double m_speed; // can only be changed through setSpeed()

    public void setSpeed(double speed) {
        // Math.max(-1.0, ...) ensures speed is never below -1.0
        // Math.min(1.0, ...)  ensures speed is never above  1.0
        // this is called "clamping" — it's in every motor wrapper ever written
        m_speed = Math.max(-1.0, Math.min(1.0, speed));
    }

    public double getSpeed() { return m_speed; }
}

SafeMotor m = new SafeMotor();
m.setSpeed(9999.0); // setSpeed clamps it to 1.0. motor is fine.
m.setSpeed(-500.0); // clamped to -1.0. safe.
// m.m_speed = 9999.0; // COMPILE ERROR: m_speed has private access in SafeMotor

public class Intake {

    // fields: PRIVATE — other classes cannot directly touch these
    private double  m_speed;
    private boolean m_isRunning;

    public Intake() {
        m_speed    = 0.0;
        m_isRunning = false;
    }

    // methods: PUBLIC — these are the "doors" other classes use to interact
    public void run(double speed) {
        m_speed    = Math.max(0.0, Math.min(1.0, speed)); // intake only goes forward
        m_isRunning = true;
    }

    public void stop() {
        m_speed    = 0.0;
        m_isRunning = false;
    }

    public boolean isRunning() { return m_isRunning; }
    public double  getSpeed()   { return m_speed; }
}

public class Motor {

    private double m_speed;

    // INSTANCE METHOD — belongs to each individual Motor object
    // can access m_speed, m_id, m_isInverted — anything on "this"
    // called as: someMotor.setSpeed(0.5)
    public void setSpeed(double speed) {
        m_speed = speed; // this.m_speed = speed (this is implied)
    }

    // STATIC METHOD — belongs to the Motor CLASS, not any object
    // no access to m_speed or "this" — there's no object context here
    // called as: Motor.clamp(1.5)  — no object needed
    // useful for pure utility functions that don't need object state
    public static double clamp(double value) {
        return Math.max(-1.0, Math.min(1.0, value)); // pure math, no fields needed
    }
}

// calling them:
Motor m = new Motor(1, false);
m.setSpeed(0.5);            // instance method — need an object
double safe = Motor.clamp(5.0); // static method — called on the class directly

public class Motor {

    private int     m_motorID;
    private double  m_speed;
    private boolean m_isRunning;

    public Motor(int motorID) {
        m_motorID  = motorID;
        m_speed    = 0.0;
        m_isRunning = false;
    }

    // GETTERS — return the private value, no parameters, just return
    // naming: getX() for most types, isX() for booleans (reads naturally)
    public double  getSpeed()   { return m_speed; }
    public int     getMotorID() { return m_motorID; }
    public boolean isRunning()  { return m_isRunning; } // isX() for booleans!!

    // SETTERS — validate input, then store it
    // naming: setX(value) where X matches the field name
    public void setSpeed(double speed) {
        // clamp to [-1.0, 1.0] so nothing can set an unsafe value
        m_speed = Math.max(-1.0, Math.min(1.0, speed));
    }

    // ACTION METHODS — verbs that do something meaningful using the object's state
    public void start(double speed) {
        setSpeed(speed);      // call our own setter — reuse its validation!!
        m_isRunning = true;
    }

    public void stop() {
        m_speed    = 0.0;
        m_isRunning = false;
    }

    /** returns a human-readable status line for logging */
    public String getStatusString() {
        return String.format("Motor %d: %.2f | %s",
            m_motorID, m_speed, m_isRunning ? "RUNNING" : "STOPPED");
    }
}

/**
 * Models the shooter mechanism.
 * Manages flywheel speed and tracks whether we're at target velocity.
 * On WRT, every subsystem class looks like this.
 */
public class ShooterSubsystem {

    // all fields: private, m_ prefixed — state owned by THIS object
    private int     m_topMotorID;
    private int     m_bottomMotorID;
    private double  m_targetSpeed;   // what speed we're ASKING for (0.0 to 1.0)
    private boolean m_isAtSpeed;     // whether flywheel has actually reached that speed

    // constructor: takes motor CAN IDs, sets safe starting state
    public ShooterSubsystem(int topID, int bottomID) {
        m_topMotorID    = topID;
        m_bottomMotorID = bottomID;
        m_targetSpeed   = 0.0;   // starts off — never spin on boot without being asked
        m_isAtSpeed     = false; // definitely not at speed when we just turned on
    }

    /** Sets the desired flywheel speed, clamped to [0.0, 1.0]. Shooters don't go backward. */
    public void setTargetSpeed(double speed) {
        m_targetSpeed = Math.max(0.0, Math.min(1.0, speed));
    }

    /** Spins up the shooter to full power. Short for setTargetSpeed(1.0). */
    public void spinUp() {
        setTargetSpeed(1.0); // reuse the setter so we still get validation
    }

    /** Stops the flywheel and clears at-speed flag. */
    public void stop() {
        m_targetSpeed = 0.0;
        m_isAtSpeed   = false; // if we're stopping, we're definitely not at speed anymore
    }

    /** @return current target speed (0.0 to 1.0) */
    public double  getTargetSpeed() { return m_targetSpeed; }

    /** @return true if the flywheel has reached target velocity */
    public boolean isAtSpeed()      { return m_isAtSpeed; }

    /** @return formatted status string for Shuffleboard */
    public String getStatusString() {
        return String.format("Shooter: %.2f | %s",
            m_targetSpeed, m_isAtSpeed ? "AT SPEED" : "SPINNING UP");
    }
}

// usage in Robot.java — this is basically how it works in the real codebase
ShooterSubsystem m_shooter = new ShooterSubsystem(7, 8); // motors on CAN 7 and 8

m_shooter.spinUp();
System.out.println(m_shooter.getTargetSpeed()); // 1.0
System.out.println(m_shooter.isAtSpeed());       // false (in reality: updated by sensors)
System.out.println(m_shooter.getStatusString()); // "Shooter: 1.00 | SPINNING UP"

public class Intake {

    private double  m_speed;
    private boolean m_isRunning;

    public Intake() { m_speed = 0.0; m_isRunning = false; }

    // setter: all validation logic lives HERE and only here
    public void setSpeed(double speed) {
        m_speed = Math.max(0.0, Math.min(1.0, speed));
    }

    // action methods just call setSpeed() — they don't duplicate the clamping
    public void runSlow()  { setSpeed(0.4); m_isRunning = true; }
    public void runFast()  { setSpeed(0.9); m_isRunning = true; }
    public void eject()    { setSpeed(0.6); m_isRunning = true; } // same direction for now

    public void stop() {
        m_speed    = 0.0;
        m_isRunning = false;
    }

    // now if clamping logic needs to change (e.g., to 0.0-0.8 for safety)
    // you ONLY change it in setSpeed() and everywhere else just works
}