Why High‑Quality Code Must Explain Its Own Decisions

Unnoticed Pattern in High‑Quality Codebases

When reviewing a senior engineer's pull request, the author noticed that the code worked and passed tests, yet three weeks later it caused a production incident—not because of a bug, but because of an undocumented assumption. By retrospectively examining many months of code reviews, the author discovered a common pattern in every high‑quality repository: the code itself explains the reasoning behind its behavior.

Code Should Explain the "Why", Not Just the "What"

Two versions of a discount‑calculation function illustrate the difference. The first version contains only the implementation:

def calculate_discount(price, user):
    if user.premium:
        return price * 0.8
    return price

The second version adds comments that capture the business decision:

def calculate_discount(price, user):
    # Premium users get 20% off to match our competitor pricing
    # Tested with focus group Aug 2023 – increased retention by 12%
    # Decision doc: docs/decisions/premium‑pricing.md
    PREMIUM_DISCOUNT_RATE = 0.20
    if user.premium:
        return price * (1 - PREMIUM_DISCOUNT_RATE)
    return price

When a future request asks to change the discount to 25 %, the second version makes it clear where to look and who to consult, while the first leaves the reason ambiguous.

Decision Context in Scalable Systems

In a fintech startup, two services handled money transfers differently. Service 1 simply enforced a hard limit:

const MAX_TRANSFER_AMOUNT = 10000;
async function createTransfer(amount, from, to) {
    if (amount > MAX_TRANSFER_AMOUNT) {
        throw new Error('Amount exceeds maximum');
    }
    // ...
}

Service 2 added extensive comments that referenced BSA regulations, legal review dates, and the rationale for the limit:

// Per BSA regulations (31 CFR 103.33), we must report transfers >$10k within 15 days.
// This limit satisfies the legal requirement, not a technical constraint.
const MAX_TRANSFER_AMOUNT = 10000;
async function createTransfer(amount, from, to) {
    if (amount > MAX_TRANSFER_AMOUNT) {
        throw new TransferLimitExceededError(`Transfers are limited to $${MAX_TRANSFER_AMOUNT} per transaction. This is a regulatory requirement, not a technical limitation.`);
    }
    // ...
}

When the CEO asked to raise the limit to $25 k, Team 1 changed the constant in minutes and shipped, while Team 2 spent two hours consulting legal, avoided a compliance breach, and documented the impact.

The Four Types of Decision Context

Business context – why a business rule exists (e.g., Stripe fees, churn reduction).

Historical context – why a particular implementation was chosen (e.g., deadlock issues with async/await).

Constraint context – external limits that shape the solution (e.g., API rate limits).

Future context – planned changes or technical debt (e.g., TODOs, pending Kafka provisioning).

All four answer the same question: "Why was this decision made?" Without this information, code appears arbitrary.

Impact of Missing Context

Data from over 200 pull requests shows a stark contrast:

PRs with decision‑context comments: average review time 12 min, 2.3 bugs found per PR, new engineers onboard in ~4 h.

PRs without such comments: average review time 28 min, 1.1 bugs per PR, onboarding takes ~2 days.

When context is absent, reviewers focus on style and miss logical bugs because they cannot understand the intent.

Practical Steps to Adopt the Pattern

In every pull request, add at least one comment that explains *why* a decision was made, not just *what* the code does.

During code review, ask "Why?" whenever you encounter a magic number, unusual pattern, or design choice, and require the author to document the answer.

Each month, record one significant decision: the problem, considered alternatives, and the chosen solution. Future maintainers will thank you.

By treating decision context as a first‑class citizen, teams can maintain high‑quality, self‑explaining codebases that survive turnover and scaling challenges.