Design Smell Detection

Smell Catalog

Refactoring Moves

Volatile Derivative

Flag any stored field whose value can be recomputed from another field, the current date, or a child collection.

// Smelly: age drifts every year
record User(LocalDate birthDate, int age) {}

// Better: derive on demand
record User(LocalDate birthDate) {
    int age() {
        return Period.between(birthDate, LocalDate.now()).getYears();
    }
}

Ask:

• Can this field be recomputed quickly?
• What update path would keep this value synchronized?
• Would deleting the stored field remove an entire class of bugs?

Prefer derived methods, projections, or query-time calculations over duplicated persisted state.

Primitive Obsession

Flag primitive fields when the domain concept has rules, formatting, or behavior.

public record Email(String value) {
    public Email {
        if (value == null || !value.contains("@")) {
            throw new IllegalArgumentException("Invalid email format");
        }
    }
}

Prefer value objects for:

• validation-heavy strings
• identifiers with formatting rules
• money, percentages, and ranges
• dates or windows with domain semantics

When reviewing, ask whether the type communicates meaning and protects itself from invalid input.

Anemic Domain Model

Flag classes that only expose state while services implement the real rules.

// Prefer behavior-rich methods over raw status mutation
order.cancel();
subscription.renewUntil(nextBillingDate);
invoice.markPaid(paymentReference);

Move logic into the domain object when the rule depends mostly on that object's own fields. Remove broad setters in favor of meaningful business operations.

Feature Envy

Flag methods that repeatedly traverse another object's data to calculate a result.

// Smelly
BigDecimal total = order.getItems().stream()
    .map(item -> item.getPrice().multiply(item.getQuantity()))
    .reduce(BigDecimal.ZERO, BigDecimal::add);

// Better
BigDecimal total = order.calculateTotal();

Prefer moving calculations, state transitions, and invariant checks to the type that owns the data being inspected.

Temporal Coupling

Flag APIs that can be misused by calling methods in the wrong order.

// Smelly
parser.init();
parser.parse(input);
parser.cleanup();

Prefer:

• constructors or static factories that return fully valid objects
• builders when many fields are required before use
• execute-around APIs that own setup and cleanup internally

Quick Heuristics

• If changing one field requires remembering to update another, suspect a volatile derivative.
• If validation appears in more than one class, suspect primitive obsession or misplaced invariants.
• If a service exceeds a few hundred lines and mostly manipulates one aggregate, suspect an anemic model.
• If a method reaches through two or more getter chains, suspect feature envy.
• If documentation says "call these methods in order," suspect temporal coupling.

Recommended Patterns

• Use value objects for domain concepts such as Email, Money, and DateRange.
• Use strategy to replace large if/switch blocks that vary behavior by type or status.
• Use builders or factories to make invalid construction impossible.
• Use dependency injection instead of new HeavyResource() inside domain or service constructors.

Review Output Shape

When reporting findings:

1. Prioritize correctness and design-risk issues over style.
2. Explain the concrete failure mode, not only the smell name.
3. Propose the smallest credible refactor.
4. Distinguish domain objects from DTOs or persistence-only shapes before recommending behavior moves.
5. Avoid forcing rich behavior into objects that are intentionally simple transport models.

Use concise findings in this form:

Smell: Volatile derivative
Why it matters: totalPrice can drift from line items during partial updates.
Better path: remove the field, compute from items, or centralize recalculation behind one business method.

Scope Boundaries

• Prefer jpa-patterns for fetch strategies, lazy loading, and query tuning.
• Prefer architecture-review for package boundaries, module direction, and layering.
• Prefer solid-principles or clean-code for broader OO refactoring beyond these domain smells.