Long parameter lists anti-pattern

A long parameter list is an API design smell when callers must remember too much positional information or when several parameters describe one concept. The issue is not a universal count; it is whether the signature communicates intent and makes incorrect calls difficult.

TL;DR

• Methods with many positional parameters force callers to memorize argument order, especially when several parameters share a type.
• Same-type positional parameters (String userId, String productId, String currency) swap silently with no compiler warning. The bug is invisible until production.
• The Parameter Object pattern bundles related arguments into a named record or class, making every field self-documenting at the call site.
• The Builder pattern handles complex construction with optional fields, defaults, and cross-field validation.
• Boolean flag parameters are a sub-smell: createOrder(..., true, false) tells the reader nothing. Use enums or separate methods instead.

The Problem

Your order service has a method that grew to eight parameters over six sprints. Each sprint added "just one more field." Nobody refactored because every call site already worked.

// Every call site is a guessing game
public class OrderService {
    public Order createOrder(
            String userId,
            String productId,
            int quantity,
            double unitPrice,
            double discountPercent,
            String currency,
            String shippingAddressId,
            boolean isGift) {
        // ... business logic
        return new Order(userId, productId, quantity,
            unitPrice, discountPercent, currency,
            shippingAddressId, isGift);
    }
}

// Spot the bug. You have five seconds.
Order order = service.createOrder(
    "prod-456",    // swapped with userId
    "user-123",    // swapped with productId
    2, 49.99, 10.0, "USD", "addr-789", false
);

The userId and productId are swapped. Both are String, so the compiler is perfectly happy. The order is placed against the wrong user, and the wrong product is charged. This class of bug is especially dangerous because the call looks type-correct even though its meaning is wrong. The example uses double to keep attention on parameter shape; production money values should use a money type such as BigDecimal.

Now imagine adding a ninth parameter (String couponCode). Every existing call site must be updated, and the insertion position determines whether the coupon code accidentally becomes the shipping address.

The compiler cannot help because String is String. Careful reading becomes harder as the number of call sites and optional behaviors grows.

Why It Happens

1. Incremental growth. The method started with 2 parameters. Each feature added one more. No single addition felt like it crossed a threshold, but six sprints later the method is unreadable.
2. Primitive obsession. Instead of modeling Money(amount, currency) or Address(id), the team passes raw primitives. Each concept adds 1-3 parameters.
3. Copy-paste momentum. Existing call sites are copied when writing new ones. Developers reproduce the argument order from memory or by copying a nearby call, propagating any existing misordering.
4. Fear of refactoring. Introducing a parameter object means changing existing call sites. That can feel risky, so the team adds another positional parameter instead.

How to Detect It

If you cannot read a call site and know what each argument means without opening the method declaration, the API needs more explicit naming or structure.

The Fix

The primary fix is the Parameter Object pattern: group related parameters into a named type. For complex optional construction, layer a Builder on top.