Matthew Boston

Explicit is better than implicit

March 26, 2025

Key takeaway: When a reader would need an unwritten convention or default to understand a piece of code, write it into the code.

Explicit code says what it means. Implicit code asks every reader to know things that aren’t written down, and some of them will guess wrong. It’s the second line of the Zen of Python, and it applies to any language.

Implicit feels convenient at first. You save a few keystrokes and lean on framework magic. Then someone new joins who doesn’t know the invisible rules. Debugging means tracing framework internals. Bugs hide in defaults that change between versions.

Python’s round is a small example. It rounds a half to the nearest even number, which suits statistics and surprises anyone reading an invoice:

from decimal import ROUND_HALF_UP, Decimal

round(2.5)                                                     # 2
Decimal("2.5").quantize(Decimal("1"), rounding=ROUND_HALF_UP)  # Decimal('3')

Naming the rounding mode puts the rule where the reader can see it.

Explicitness pays off most at boundaries. A function called validate_and_normalize_email beats one called process. If your team has to look up a default, write it down, like passing a timeout to requests.get, which has none by default. Pass dependencies in instead of pulling them from a container:

# receipts.py: the caller can see it sends mail, and a test can pass a fake.
def send_receipt(order_id: str, mailer: Mailer) -> None:
    order = find_order(order_id)
    mailer.send(order.email, order.receipt)

Explicit doesn’t mean verbose. Verbose code adds words without adding information, while explicit code adds exactly the information that would otherwise be hidden. A one-liner that leans on three implicit conversions is short, but that doesn’t make it clear.

Implicit conventions work fine for the one person who wrote them. Codebases grow and teams change, and what felt obvious to three people becomes tribal knowledge twenty people have to reconstruct.