← Back to System Internals

Code Smells — A Practical Refactoring Guide

A working reference to the classic code smells — the surface symptoms of deeper design trouble — and the refactorings that clear them.

A code smell is a hint. It is a pattern in your source that, more often than not, signals a design weakness worth addressing. The value of the vocabulary is speed: once a team shares names like “Feature Envy” or “Shotgun Surgery,” a reviewer can point at a problem in two words instead of a paragraph, and everyone knows roughly what fix to reach for. This guide walks the five families of smells, gives the typical refactoring for each, and ends with a cheat sheet you can keep open during a review.

1. What is a code smell

A code smell is a surface symptom that usually points to a deeper design problem. It is not a bug — the program can compile, pass its tests, and ship with every smell in this guide intact. What a smell tells you is that the code will be harder than it should be to read, change, or extend later. It is a prompt to look closer, not a verdict.

The critical caveat: smells are heuristics, not rules. A long method in a hot loop may be exactly right; a tiny class that looks “lazy” may earn its keep as a domain concept. The discipline is to notice the smell, ask whether it is actually hurting you, and refactor only when the answer is yes. Treat the catalog as a checklist for your intuition, never as a linter that must be obeyed.

2. Bloaters

Bloaters are code, methods, and classes that have grown so large they are hard to work with. They rarely start big — they accrete, one “just one more line” at a time, until nobody wants to touch them.

• Long Method — a function doing too many things at too many levels of detail. Fix with Extract Method: pull each coherent chunk into a well-named helper until the original reads like a summary.
• Large Class — a class with too many fields and responsibilities. Fix with Extract Class (split off a cohesive group of fields and methods) or Extract Subclass.
• Long Parameter List — four, five, six parameters that are hard to remember and easy to transpose. Fix with Introduce Parameter Object or Preserve Whole Object so related arguments travel together.
• Data Clumps — the same few data items appearing together in many places (say start, end, timezone). If they always travel as a group, they want to be a class. Fix with Extract Class then Introduce Parameter Object.
• Primitive Obsession — using raw strings and ints to model concepts that deserve a type (a currency amount as a bare float, a phone number as a str). Fix by replacing the primitive with a small value object or type.

The workhorse fix is Extract Method. Before — one function juggling validation, calculation, and formatting:

def print_invoice(order):
    # validate
    if not order.items:
        raise ValueError("empty order")
    # calculate
    total = 0
    for item in order.items:
        total += item.price * item.qty
    if order.customer.is_gold:
        total *= 0.85
    # format
    print(f"Invoice for {order.customer.name}")
    print(f"Total: ${total:.2f}")

After — each concern named and separated, and the top function reads like a table of contents:

def print_invoice(order):
    _validate(order)
    total = _order_total(order)
    _render(order.customer, total)


def _validate(order):
    if not order.items:
        raise ValueError("empty order")


def _order_total(order):
    subtotal = sum(item.price * item.qty for item in order.items)
    return subtotal * 0.85 if order.customer.is_gold else subtotal


def _render(customer, total):
    print(f"Invoice for {customer.name}")
    print(f"Total: ${total:.2f}")

3. Object-Orientation Abusers

These smells are incomplete or incorrect uses of object-oriented mechanisms — polymorphism, inheritance, interfaces — where the code fights the paradigm instead of leaning on it.

• Switch Statements (type codes) — a switch or if/elif chain branching on a type code, especially when the same chain reappears elsewhere. Fix with Replace Conditional with Polymorphism: give each type a class and let dispatch do the branching.
• Refused Bequest — a subclass that inherits methods or data it does not want and does not use, hinting the inheritance is wrong. Fix by Push Down the unwanted members, or replace inheritance with delegation.
• Temporary Field — a field that is only set and meaningful during part of an object’s life, sitting empty the rest of the time and confusing every reader. Fix by Extract Class for the field and its related logic, or pass it as a parameter instead.
• Alternative Classes with Different Interfaces — two classes that do the same job but expose different method names and signatures. Fix by renaming and aligning the interfaces (Rename Method, Move Method) so they become interchangeable.

4. Change Preventers

These smells make change expensive: one conceptual change forces edits in many unrelated places, or in the wrong number of places. They are the most direct tax on velocity.

• Divergent Change — one class changes for many different reasons (a change to the database and the tax rules and the report layout all touch the same file). The class is doing too many jobs. Fix with Extract Class so each reason for change lives in one place.
• Shotgun Surgery — the mirror image: one change forces small edits scattered across many classes. The responsibility is smeared too thin. Fix with Move Method and Move Field to pull the scattered behavior into a single class.
• Parallel Inheritance Hierarchies — every time you add a subclass in one hierarchy you must add a matching subclass in another. Fix by having one hierarchy refer to instances of the other so the duplication collapses.

5. Dispensables

Dispensables are things whose absence would make the code cleaner. They add volume and reading cost without adding value.

• Duplicate Code — the same structure in more than one place; the single most common smell. Fix with Extract Method (within a class), Pull Up Method (across subclasses), or Extract Class for shared behavior.
• Dead Code — a variable, parameter, method, or class no longer used. Delete it — version control remembers it if you ever need it back.
• Lazy Class — a class that no longer does enough to justify its existence. Fix with Inline Class, folding it into its only caller.
• Speculative Generality — abstractions, hooks, and parameters built for a future that never came (“we might need this someday”). Fix by collapsing the unused hierarchy, inlining the class, and removing the unused parameters. YAGNI.
• Data Class — a class that is only fields and getters/setters, with all the behavior that operates on it living elsewhere. Fix by Move Method to bring the relevant behavior onto the data it uses.
• Comments as deodorant — a block of comments explaining what a tangle of code does is often masking a smell. Try to Extract Method with a name that says what the comment said; if the code explains itself, the comment can go. Keep comments that explain why.

6. Couplers

Couplers are smells of excessive coupling between classes — or, in the case of Middle Man, of coupling avoided so aggressively that a class stops pulling its weight.

• Feature Envy — a method more interested in another class’s data than its own, reaching across to grab several of its fields. Fix with Move Method to put the behavior where the data lives.
• Inappropriate Intimacy — two classes reaching deep into each other’s internals. Fix by Move Method / Move Field to reduce the shared surface, or extract the shared part into its own class.
• Message Chains — a client walking a long path like a.getB().getC().getD().doThing(), coupling itself to the whole navigation structure. Fix with Hide Delegate: give the first object a method that hides the chain.
• Middle Man — a class where most methods just delegate to another class, adding nothing. Fix with Remove Middle Man and let clients talk to the real object directly.

7. Smell-to-refactoring cheat sheet

8. How to use smells well

Knowing the catalog is the easy part; using it without wrecking a working system is the skill. The loop below keeps refactoring safe — behavior never changes, only structure.

• Smells guide; they don’t govern. Use them to find candidates for improvement, then judge each one on its merits. Not every smell needs a fix today.
• Tests protect. Refactoring means changing structure without changing behavior — a test suite is what lets you prove you did exactly that.
• Refactor in small steps. Make one named refactoring at a time and keep the code compiling and green throughout. Small steps are easy to reason about and easy to undo.
• Don’t refactor without coverage. If the area has no tests, add characterization tests first. Refactoring blind is just editing and hoping.
• Follow the Boy Scout rule. Leave each file a little cleaner than you found it. Small, opportunistic cleanups compound faster than big rewrites.
• Review for smells. Bring the shared vocabulary into code review — naming a smell is a fast, low-heat way to flag a design concern.

9. Summary