Demo: modeling the parking garage from requirements

Written Explanation

Step 1: the requirements

A parking garage has several levels. Each level has parking spots, and each spot is small, medium, or large. A vehicle is also small, medium, or large and needs a spot at least as big as itself. A driver who enters gets a ticket. On leaving, the driver pays a fee based on the hours parked, rounded up to full hours, at a rate that depends on the spot size: 2, 3, or 4 per hour. A ticket can be used only once.

Step 2: nouns, verbs, rules

• Nouns: garage, level, spot, size, vehicle, driver, ticket, fee, hour, rate.
• Verbs: park (enter, get a ticket), leave (pay), fit.
• Rules: a vehicle needs a spot at least as big; a spot holds one vehicle at a time; a ticket is used once; hours are rounded up.

Sorting as in lesson 1:

A tempting trap. "Vehicles are small, medium, or large" invites Car, Truck, Motorbike subclasses. But what differs between vehicles in this text is only one value, the size. That is exactly the premature inheritance from lesson 1: subclasses that differ by one piece of data. One Vehicle class with a SpotSize field does the job. Oracle's tutorial describes an enum as the type to use for a fixed set of constants, and notes that an enum can have fields and methods. We use that: the size comparison lives in the enum.

Step 3: assign responsibilities

Step 4: sketch the UML

Garage 1 ◆------- * Level
Level  1 ◆------- * Spot
Garage 1 -------- 1 FeePolicy          (HourlyFeePolicy implements FeePolicy)
Ticket * -------- 1 Spot
Ticket * -------- 1 Vehicle
Spot / Vehicle   -> SpotSize (an enum)

Step 5: the planned mistake, then the fix

The first version of Garage.leave calculates the fee itself, because that is where leaving is processed. It looks harmless:

int leave(Ticket t, int now) {
    t.markUsed();
    t.spot().free();
    int hours = (t.minutesParked(now) + 59) / 60;
    int rate;
    if (t.spot().size() == SpotSize.SMALL) rate = 2;
    else if (t.spot().size() == SpotSize.MEDIUM) rate = 3;
    else rate = 4;
    return hours * rate;
}

It compiles and gives the right answer. But apply the "and" test to Garage: it finds spots and manages tickets and knows pricing rules. Think of the next feature requests: a weekend rate, a daily maximum, a free first half hour. Every one edits Garage, in the middle of the code that frees spots. Each request adds another if, and the class slowly turns into a god class with pricing mixed into parking. The rate also does not belong to the garage's main job; it changes for business reasons.

The fix is the extraction from lesson 3: a FeePolicy interface with one implementation, and Garage only calls it.

interface FeePolicy { int fee(int minutes, SpotSize size); }

class HourlyFeePolicy implements FeePolicy {
    public int fee(int minutes, SpotSize size) {
        int hours = (minutes + 59) / 60;          // round up to whole hours
        int rate = 2 + size.ordinal();            // 2, 3, 4 per hour
        return hours * rate;
    }
}

size.ordinal() is the position of the constant in the enum declaration (0, 1, 2 here). It is a shortcut that works only while SMALL, MEDIUM, LARGE stay in this order and the rates stay a straight line. We will list it as a risk in the rationale. After the move, the output was identical to the version with the if chain.

Step 6: the whole design, with a scenario

import java.util.ArrayList;
import java.util.List;

enum SpotSize {
    SMALL, MEDIUM, LARGE;
    boolean canHold(SpotSize vehicleSize) { return this.ordinal() >= vehicleSize.ordinal(); }
}

class Vehicle {
    private final String plate;
    private final SpotSize size;
    Vehicle(String plate, SpotSize size) { this.plate = plate; this.size = size; }
    String plate() { return plate; }
    SpotSize size() { return size; }
}

class Spot {
    private final String id;
    private final SpotSize size;
    private boolean occupied;
    Spot(String id, SpotSize size) { this.id = id; this.size = size; }
    String id() { return id; }
    SpotSize size() { return size; }
    boolean canFit(Vehicle v) { return !occupied && size.canHold(v.size()); }
    void occupy() {
        if (occupied) throw new IllegalStateException("spot " + id + " is taken");
        occupied = true;
    }
    void free() { occupied = false; }
}

class Level {
    private final List<Spot> spots = new ArrayList<>();
    void add(Spot spot) { spots.add(spot); }
    Spot findSpotFor(Vehicle v) {
        for (Spot s : spots) {
            if (s.canFit(v)) return s;
        }
        return null;
    }
}

class Ticket {
    private final Vehicle vehicle;
    private final Spot spot;
    private final int entryMinute;
    private boolean used;
    Ticket(Vehicle vehicle, Spot spot, int entryMinute) {
        this.vehicle = vehicle; this.spot = spot; this.entryMinute = entryMinute;
    }
    Vehicle vehicle() { return vehicle; }
    Spot spot() { return spot; }
    int minutesParked(int now) { return now - entryMinute; }
    void markUsed() {
        if (used) throw new IllegalStateException("ticket already used");
        used = true;
    }
}

class Garage {
    private final List<Level> levels = new ArrayList<>();
    private final FeePolicy fees;
    Garage(FeePolicy fees) { this.fees = fees; }
    void addLevel(Level level) { levels.add(level); }

    Ticket park(Vehicle v, int now) {
        for (Level level : levels) {
            Spot spot = level.findSpotFor(v);
            if (spot != null) {
                spot.occupy();
                return new Ticket(v, spot, now);
            }
        }
        throw new IllegalStateException("no free spot for " + v.plate());
    }

    int leave(Ticket t, int now) {
        t.markUsed();
        t.spot().free();
        return fees.fee(t.minutesParked(now), t.spot().size());
    }
}

FeePolicy and HourlyFeePolicy are as in step 5. Times are minutes since the garage opened, a shortcut that a date-time class would replace in a real project. Now a main that builds one level with a small spot G1 and a large spot G2 and runs the scenario:

Ticket car = garage.park(new Vehicle("CAR-1", SpotSize.SMALL), 0);
Ticket van = garage.park(new Vehicle("VAN-1", SpotSize.LARGE), 10);
// a third vehicle, no free spot
System.out.println("fee " + garage.leave(car, 130));
// the same ticket again
// a new car arrives at minute 150

CAR-1 in G1
VAN-1 in G2
no free spot for CAR-2
fee 6
ticket already used
CAR-2 in G1

Read the output as a story. The car takes the small spot; the van the large one; a second car finds none and is refused (the failure scenario). The first car leaves after 130 minutes: three started hours at 2 is 6. Reusing the ticket is rejected, and the freed spot G1 is reused by the next car. Notice what Garage does not contain: no size comparison, no rate numbers, no ticket flag arithmetic.

Step 7: a three-line rationale

Decisions. One Vehicle class with a SpotSize enum, rejecting Car/Truck subclasses, because vehicles differ only by size; cost: if trucks get special rules, I must revisit. Fees live in a FeePolicy interface, rejecting an if chain in Garage, because rates change for business reasons; cost: one more type. Risk. 2 + ordinal() couples the rate to the enum order and cannot express arbitrary rates. Garage.park returns after the first level with a free spot, which is a simple strategy, not an optimal one. Next. Per-spot-size rate table; spots on several levels; a date-time clock.