The Smell Map: From Symptom to Cure

Every smell this course has met fits one of five families, and each family has one cause and a short list of cures; three questions (what changes together, what has no home, who knows too much) diagnose a smell you've never seen, and the smallest cure, often pulling out a method, comes first.

Journeyman · Software Development · OOP · Updated

By

After this lesson you can

  • Diagnose a smell you haven't met by asking what changes together, what has no home, and who knows too much
  • Match a smell to its family and its cure on the smell map, and say when pulling out a method is enough

Key takeaways

  • Every smell in the course belongs to one of five families: choosing, making, tangling, size and combining, each with one cause underneath.
  • To diagnose a smell you haven't met, ask three questions: what has to change together, what decision or job has no home, and who knows too much.
  • Try the smallest cure first: pull out a method, move a method, give something a name. Reach for a pattern when the next requirement shows the small cure won't hold.
  • Pulling out a method cures more smells than any pattern, because most smells are a job or a decision without a home, and a method is the smallest home there is.

Before this: the five family lessons, from Smells of Choosing to Smells of Combining.

You've now read every family of smells in Summit Gym's code. Next week you'll open a codebase this course has never shown you, and its smells won't come with a label. A list of smells to memorize won't help much there; there are dozens, and every team's code invents new ones. What helps is a map: every smell you've met, grouped by what causes it, and a way to place a new one on it.

A doctor's clipboard chart titled "Summit Gym's booking system", with five rows, one for each family of smells: Choosing, Making, Tangling, Size and Combining, and three columns headed Symptom, Cause and Cure

The map

Every pattern lesson in this course began with a smell. Here they all are, by family. Each family has one cause, so if you can name the family, you already know what's wrong underneath. Each lesson is named by the start of its title.

Smell (the symptom) Family Cure Where you met it
The same switch on a kind in many places Choosing Polymorphism, or a dictionary Smells of Choosing
A switch on a rule's name, in code that shouldn't change Choosing Strategy Weekly Deals; Strategy
A status switch in every method Choosing State State
A true/false argument that changes what a method does Choosing Two methods Smells of Choosing
"What kind are you?" checks before acting Choosing Polymorphism Smells of Choosing
The same if chain that picks a class, in several places Making A factory, or a dictionary of functions Simple Factory; Factories the Modern Way
Two copies of something the whole app must share Making One object, made at the start and handed in Singleton; Why Singleton Is Usually a Trap
Tests that pass alone and fail together Making Hand in one object; each test makes its own Why Singleton Is Usually a Trap
A class that builds what it needs (its database, the clock) Making Dependency injection Smells of Making; Dependency Injection
A constructor with a long list of arguments Making Builder, or named arguments Builder; Builders the Modern Way
Rebuilding "the same as last time", field by field Making Prototype Prototype
Parts from different families mixed by mistake Making Abstract Factory Abstract Factory
Something expensive, made again and again Making An object pool, or lazy loading Object Pool and Lazy Loading
A chain of calls that reaches through objects Tangling Move the method Smells of Tangling
One small change that touches many files Tangling Gather the rule in one place Smells of Tangling
The same steps, in the same order, in every caller Tangling Facade Facade
One method that calls everyone who cares, growing with each one Tangling Observer Observer
Parts that all call each other Tangling Mediator Mediator
Another system's odd calls all through your code Tangling Adapter Adapter
Business rules that know how the data is stored Tangling Repository Repository
Code that has to know how a collection is stored to walk it Tangling Iterator Iterator
An action done by a direct call, which can't be stored or undone Tangling Command Command
A new job that means a new method on every class Tangling Visitor Visitor
A long method, with comments marking its sections Size Pull out a method Smells of Size
A class that does everything Size Pull out a class Smells of Size
The same steps, copied with one step different Size Template Method, or Strategy Template Method
A long row of checks, each deciding whether to go on Size Chain of Responsibility Chain of Responsibility
A page that loads data, shows it and handles clicks Size Model, view and controller MVC
Hard-coded rules that the users want to write themselves Size Interpreter Interpreter
The same data stored in thousands of objects Size Flyweight Flyweight
A class for every combination of features Combining Decorator, or a list of extras Smells of Combining; Decorator
A class for every pair of two things that vary Combining Bridge Bridge
The same "is it missing?" check before every use Combining Null Object Smells of Combining; Null Object
One thing and a group of things, told apart everywhere Combining Composite Composite
Extra jobs (a cache, a log, a permission check) pasted around every call Combining Decorator, Proxy, or middleware Decorator; Proxy; Middleware
A call to a far-away service with no plan for when it fails Combining Retry, and a circuit breaker Retry; Circuit Breaker

And the five causes, one per family:

  • Choosing: one decision, copied everywhere.
  • Making: the code that uses an object also decides how to make it.
  • Tangling: code that knows too much about how other objects are put together.
  • Size: jobs that never got a name of their own.
  • Combining: mixes built by copying, instead of from small parts.

The smell map: five columns, one per family (choosing, making, tangling, size, combining), each headed by its cause, with three symptoms pointing to their cures. A banner along the bottom: "First try the smallest cure: pull out a method, move a method, give it a name."

A smell you haven't met

The map doesn't have every smell in the world, and it doesn't need to. Here's one it doesn't list: the gym's reminder texts, which go out the evening before each class:

SendReminders(new List<(string, string, int)> { ("Maya", "Yoga", 7), ("Sam", "Spin", 12), ("Leo", "HIIT", 18) });

void SendReminders(List<(string Name, string Kind, int Hour)> bookings)
{
    foreach ((string name, string kind, int hour) in bookings)
    {
        // Work out the start time as text, such as "7:00 AM" or "6:00 PM".
        string suffix = hour < 12 ? "AM" : "PM";
        int shown = hour <= 12 ? hour : hour - 12;
        string start = quot;{shown}:00 {suffix}";
        Console.WriteLine(quot;Reminder for {name}: {kind} tomorrow at {start}");
    }
}
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
record Booking(String name, String kind, int hour) {}

void sendReminders(List<Booking> bookings) {
    for (Booking booking : bookings) {
        // Work out the start time as text, such as "7:00 AM" or "6:00 PM".
        String suffix = booking.hour() < 12 ? "AM" : "PM";
        int shown = booking.hour() <= 12 ? booking.hour() : booking.hour() - 12;
        String start = shown + ":00 " + suffix;
        IO.println("Reminder for " + booking.name() + ": " + booking.kind() + " tomorrow at " + start);
    }
}

void main() {
    sendReminders(List.of(new Booking("Maya", "Yoga", 7), new Booking("Sam", "Spin", 12), new Booking("Leo", "HIIT", 18)));
}
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
def send_reminders(bookings):
    for name, kind, hour in bookings:
        # Work out the start time as text, such as "7:00 AM" or "6:00 PM".
        suffix = "AM" if hour < 12 else "PM"
        shown = hour if hour <= 12 else hour - 12
        start = f"{shown}:00 {suffix}"
        print(f"Reminder for {name}: {kind} tomorrow at {start}")


send_reminders([("Maya", "Yoga", 7), ("Sam", "Spin", 12), ("Leo", "HIIT", 18)])
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
function sendReminders(bookings) {
  for (const [name, kind, hour] of bookings) {
    // Work out the start time as text, such as "7:00 AM" or "6:00 PM".
    const suffix = hour < 12 ? "AM" : "PM";
    const shown = hour <= 12 ? hour : hour - 12;
    const start = `${shown}:00 ${suffix}`;
    console.log(`Reminder for ${name}: ${kind} tomorrow at ${start}`);
  }
}

sendReminders([["Maya", "Yoga", 7], ["Sam", "Spin", 12], ["Leo", "HIIT", 18]]);
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
function sendReminders(bookings: [string, string, number][]): void {
  for (const [name, kind, hour] of bookings) {
    // Work out the start time as text, such as "7:00 AM" or "6:00 PM".
    const suffix = hour < 12 ? "AM" : "PM";
    const shown = hour <= 12 ? hour : hour - 12;
    const start = `${shown}:00 ${suffix}`;
    console.log(`Reminder for ${name}: ${kind} tomorrow at ${start}`);
  }
}

sendReminders([["Maya", "Yoga", 7], ["Sam", "Spin", 12], ["Leo", "HIIT", 18]]);
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM

The owner now wants the weekly schedule to show start times the same way. Something smells, but which smell? Ask three questions, in order:

  1. What has to change together? The schedule and the reminders must show times the same way. If the format changes (say, to "7 AM"), both must change.
  2. What decision or job has no home? "Turn an hour into text" is a job, and it has no name: it's three lines in the middle of a loop, with a comment explaining them. That answer places it on the map, in the size family: a job that never got a name.
  3. Who knows too much? The reminder loop knows how times are formatted, which isn't its job.

The comment is the clue. A comment that explains what the next lines do is the name of a job, waiting to become a method. Books on smells list it as its own smell, comments, and its cure is the plainest one on the map:

SendReminders(new List<(string, string, int)> { ("Maya", "Yoga", 7), ("Sam", "Spin", 12), ("Leo", "HIIT", 18) });
Console.WriteLine(quot;Schedule: HIIT at {StartText(18)}");

void SendReminders(List<(string Name, string Kind, int Hour)> bookings)
{
    foreach ((string name, string kind, int hour) in bookings)
    {
        Console.WriteLine(quot;Reminder for {name}: {kind} tomorrow at {StartText(hour)}");
    }
}

string StartText(int hour)
{
    string suffix = hour < 12 ? "AM" : "PM";
    int shown = hour <= 12 ? hour : hour - 12;
    return quot;{shown}:00 {suffix}";
}
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
Schedule: HIIT at 6:00 PM
record Booking(String name, String kind, int hour) {}

String startText(int hour) {
    String suffix = hour < 12 ? "AM" : "PM";
    int shown = hour <= 12 ? hour : hour - 12;
    return shown + ":00 " + suffix;
}

void sendReminders(List<Booking> bookings) {
    for (Booking booking : bookings) {
        IO.println("Reminder for " + booking.name() + ": " + booking.kind() + " tomorrow at " + startText(booking.hour()));
    }
}

void main() {
    sendReminders(List.of(new Booking("Maya", "Yoga", 7), new Booking("Sam", "Spin", 12), new Booking("Leo", "HIIT", 18)));
    IO.println("Schedule: HIIT at " + startText(18));
}
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
Schedule: HIIT at 6:00 PM
def start_text(hour):
    suffix = "AM" if hour < 12 else "PM"
    shown = hour if hour <= 12 else hour - 12
    return f"{shown}:00 {suffix}"


def send_reminders(bookings):
    for name, kind, hour in bookings:
        print(f"Reminder for {name}: {kind} tomorrow at {start_text(hour)}")


send_reminders([("Maya", "Yoga", 7), ("Sam", "Spin", 12), ("Leo", "HIIT", 18)])
print(f"Schedule: HIIT at {start_text(18)}")
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
Schedule: HIIT at 6:00 PM
function startText(hour) {
  const suffix = hour < 12 ? "AM" : "PM";
  const shown = hour <= 12 ? hour : hour - 12;
  return `${shown}:00 ${suffix}`;
}

function sendReminders(bookings) {
  for (const [name, kind, hour] of bookings) {
    console.log(`Reminder for ${name}: ${kind} tomorrow at ${startText(hour)}`);
  }
}

sendReminders([["Maya", "Yoga", 7], ["Sam", "Spin", 12], ["Leo", "HIIT", 18]]);
console.log(`Schedule: HIIT at ${startText(18)}`);
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
Schedule: HIIT at 6:00 PM
function startText(hour: number): string {
  const suffix = hour < 12 ? "AM" : "PM";
  const shown = hour <= 12 ? hour : hour - 12;
  return `${shown}:00 ${suffix}`;
}

function sendReminders(bookings: [string, string, number][]): void {
  for (const [name, kind, hour] of bookings) {
    console.log(`Reminder for ${name}: ${kind} tomorrow at ${startText(hour)}`);
  }
}

sendReminders([["Maya", "Yoga", 7], ["Sam", "Spin", 12], ["Leo", "HIIT", 18]]);
console.log(`Schedule: HIIT at ${startText(18)}`);
Reminder for Maya: Yoga tomorrow at 7:00 AM
Reminder for Sam: Spin tomorrow at 12:00 PM
Reminder for Leo: HIIT tomorrow at 6:00 PM
Schedule: HIIT at 6:00 PM

The reminders print exactly what they did, and the schedule reuses startText instead of copying it. The comment is gone, because the method's name says it. No pattern was needed, and none would have helped.

Why "pull out a method" wins so often

Look down the map's causes again: a decision with no home, a job with no name, knowledge in the wrong place. A method is the smallest home a piece of code can have. So the smallest cures, pull out a method (books call it Extract Method), move a method to the object whose data it uses, and give it a name, cure more smells than all the patterns put together. Changing code's shape without changing what it does, one small step at a time, is called refactoring, and these are its everyday moves.

The patterns aren't a different kind of cure. They're those moves, grown up: a Strategy is a method you can hand in, a Template Method is a method with one step left open, a factory is a method that says new. So the order to try them is:

  1. The smallest cure first. Pull out, move, rename.
  2. Then ask about the next requirement. If the gym adds a sixth kind of class next month, will the small cure still hold? If a new kind means editing five places again, it's time for the pattern on the map.
  3. No cure at all is sometimes right. A switch in one place, on two kinds that will never change, isn't a smell. It's code.

Check yourself

2 questions to try on the lesson page.

So what

You don't need to have seen a smell before to treat it. Ask what changes together, what has no home and who knows too much, find its family on the map, and try the smallest cure first. Most of the time, that's a method with a good name.

Key terms

Cheat sheets