Magic numbers anti-pattern

TL;DR

• Magic numbers are literal values embedded in code with no explanation of what they represent or why that specific value was chosen.
• if (retries > 3) tells nothing about intent. Is 3 the max retries? A timeout multiplier? A coincidence? Nobody knows without reading surrounding context or git blame.
• Divergent constants are the silent killer: the same value copied in 12 places gets updated in 10 and left stale in 2, causing subtle bugs that surface months later.
• Named constants (static final), enums for domain sets, and externalized configuration are the three-tier fix.
• The "zero, one, infinity" constants (0, 1, "", true, false) are universally understood and do not need extraction.

The Problem

Your order processing service has grown over two years. Business rules are encoded as raw numbers scattered across 14 files. A product manager asks: "Can we change the free shipping threshold from $50 to $75?" The developer searches for 50 and finds 87 occurrences in the codebase.

// Magic numbers everywhere. What does each one mean?
public class OrderProcessor {
    public void process(Order order) {
        if (order.total() > 50.0) {
            applyFreeShipping(order);
        }

        if (order.items().size() > 100) {
            throw new OrderException("Too many items");
        }

        if (order.total() > 500.0) {
            applyBulkDiscount(order, 10);
        }

        if (order.total() < 0.01) {
            throw new OrderException("Amount too small");
        }

        scheduleConfirmation(order, 5000);
    }
}

What does 50.0 represent? Free shipping threshold? Fraud check limit? Minimum for insurance? What does 10 mean in applyBulkDiscount? Ten percent? Ten dollars? Ten items? The developer who wrote this six months ago remembers. Nobody else does.

I've debugged an incident where the free shipping threshold of 50 appeared in three files. One developer updated two files to 75 for a promotion. The third file (a background aggregation job) still used 50, so the nightly revenue report showed different free-shipping counts than the checkout flow. The discrepancy was not noticed for six weeks.

When you search for 50 in a codebase, you find port numbers, array sizes, timeout values, and actual dollar amounts. There is no way to distinguish the free shipping threshold from Thread.sleep(50) without reading every occurrence.

Why It Happens

1. Prototype permanence. The developer writes if (retries > 3) during prototyping, intending to extract a constant "later." Later never comes. The prototype ships to production.
2. Context amnesia. The author knows that 86400 is seconds-per-day at write time. Six months later, even the author does not recognize it without counting zeros.
3. Copy-paste propagation. One magic number is copied to a second file, then a third. Each copy is independently maintained (or not), and divergence is inevitable.
4. Premature concreteness. The developer thinks "the retry limit is always 3" and hardcodes it, not realizing that different environments or service tiers need different values.

How to Detect It

My rule of thumb: if a reviewer would need to ask "why this specific number?", it needs a name.

The Fix

The fix has three tiers: named constants for single values, enums for domain sets, and externalized config for runtime-tunable values.