magic-value-elimination

Every Literal Deserves a Name

If a value appears in code without a name explaining what it means, it is a magic value. Magic values are not "minor style issues." They are comprehension failures. When a reader sees 86400, they must stop, count zeros, divide by 60 twice, and conclude "oh, seconds per day." When they see SECONDS_PER_DAY, they keep reading. That interruption -- multiplied by every developer, every review, every debugging session -- is the cost of a magic value.

Eliminate them. All of them.

The Rule

If a value appears in code without a name explaining what it means, it is a magic value and it must be eliminated.

No exceptions for "obvious" values. No exceptions for "it is only used once." No exceptions for "everyone knows what 200 means." Name it. The name is documentation that never goes stale, a grep target that always works, and a single point of change when the value evolves.

Magic Numbers

Every number that is not 0, 1, or -1 in an obvious context needs a name.

GOOD:

SECONDS_PER_DAY = 86400
MAX_BATCH_SIZE = 1000
RELEVANCE_THRESHOLD = 0.5
MAX_RETRY_ATTEMPTS = 3
DEFAULT_PAGE_SIZE = 20
BCRYPT_ROUNDS = 12
HTTP_TIMEOUT_SECONDS = 30
CACHE_TTL_MINUTES = 15
MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024  # 10 MB

BAD:

if elapsed > 86400:
    expire_session()

results = results[:1000]

if score < 0.5:
    discard(item)

for attempt in range(3):
    try:
        response = client.post(url, timeout=30)
        break
    except Timeout:
        time.sleep(2 ** attempt)

The reader of the bad code must reverse-engineer the meaning of every number. 86400 -- is that seconds? Milliseconds? Why that specific value? 1000 -- is that a page size? A rate limit? An arbitrary cap? 0.5 -- half of what? 3 -- why three? 30 -- thirty what?

Magic Strings

String literals that represent categories, statuses, types, roles, or any value from a finite set must be enums or named constants. No inline strings.

GOOD -- Python: