A shipping calculation puts the advice to work

The following is an original teaching example, not code from the book. Imagine a fictional store where an order with a subtotal of at least 20,000 cents qualifies for free shipping. Below that threshold, shipping costs 1,500 cents. The total is the sum of those amounts. Discounts, taxes and external services are outside this example.

An initial implementation might put everything inside process(order): add the items, check the threshold, charge the customer and send an email. Extracting the calculation creates a useful boundary because a reviewer can examine the pricing rule without executing a charge. The minimal version below uses Python 3 with no dependencies. Running it passes all checks and exits without output:

FREE_SHIPPING_THRESHOLD_CENTS = 20_000
STANDARD_SHIPPING_CENTS = 1_500


def shipping_cents(subtotal_cents: int) -> int:
    if subtotal_cents < 0:
        raise ValueError("subtotal must be nonnegative")
    if subtotal_cents >= FREE_SHIPPING_THRESHOLD_CENTS:
        return 0
    return STANDARD_SHIPPING_CENTS


def total_cents(subtotal_cents: int) -> int:
    return subtotal_cents + shipping_cents(subtotal_cents)


assert total_cents(0) == 1_500
assert total_cents(19_999) == 21_499
assert total_cents(20_000) == 20_000
assert total_cents(25_000) == 25_000

try:
    total_cents(-1)
except ValueError:
    pass
else:
    raise AssertionError("negative subtotal was accepted")

The 19,999 case makes the boundary visible. Testing only a cheap order and an expensive order would leave the distinction between > and >= without direct protection. The zero case exposes a potentially odd decision: an empty order still incurs shipping. The code implements the stated rule, but a real team would need to ask the product owner whether that behavior belongs in production.

The extraction earns its place because shipping_cents names a concept that can be explained independently. Adding helpers called is_high_enough, get_standard_value and add_values would break up a calculation that already fits comfortably in the reader's working memory. Individual functions would become shorter while navigation increased. My preference here is to keep the comparison close to its result.

These assertions check only the cases shown. They do not establish equivalence with an existing checkout, enforce runtime types or handle multiple currencies. They do not solve idempotency, prices changing during purchase, persistence or payment-provider failures either. The clarity gain is local and should be described that way. A real refactoring would need protection for the existing behavior before replacing its calculation.

This is also why a neat snippet cannot settle an architectural debate. The same calculation may need a different boundary when several pricing policies vary independently or when a public contract must remain compatible. Review the change the system actually needs before adding extension points for hypothetical requirements.

Comments and tests should preserve information

A comment saying "add shipping to the subtotal" contributes little beside the return statement in total_cents. A comment recording the commercial reason for the threshold, with a reference to the decision, could prevent someone from "correcting" it later. Whether a comment helps depends on the information the code can communicate. Names describe operations, but they do not always explain why a constraint exists.

I would be particularly careful around protocols, algorithms and compatibility workarounds. Removing a note about a supplier's defective behavior can erase the reason for an apparently redundant condition. Compare the cost of maintaining that note with the cost of rediscovering the decision. Public contract documentation also serves people who should not have to read the implementation to use it safely.

Tests help identify what a review must preserve. In the example, names communicate units while the cases communicate the threshold. Giving every private helper a rigid test could make a change in decomposition break the suite without changing any result. I would favor observable contracts and reserve internal tests for logic that merits independent verification. Otherwise, the suite can make harmless restructuring unnecessarily expensive.

Where the advice needs resistance

The most questionable move is treating function length as a substitute for simplicity. A short routine can depend on several external concepts; a longer routine can present a coherent sequence. I would examine how much information a reader must hold to make a specific change. A line count cannot answer that question on its own.

There is an identifiable alternative perspective. John Ousterhout explicitly describes disagreements with Martin about method length and comments on his A Philosophy of Software Design page. I recommend comparing those perspectives against the same piece of your own code. If an extraction adds an interface while leaving callers dependent on all its internal details, its benefit still needs to be demonstrated.

The book's 2008 context matters as well. Its association with Java and object-oriented examples calls for care when applying its organization to functional code, data pipelines or performance-sensitive routines. Extra objects and calls may suit one service and be inconvenient elsewhere. Any performance claim requires representative measurement; applying a cleanliness heuristic does not remove that obligation.

An indiscriminate recommendation can also ignore a team's immediate situation. A system with little test coverage, urgent delivery and poorly understood behavior needs a safe change strategy. Broad cleanup can use the available delivery window while introducing regressions. Choose a boundary needed for the current change, document its contract and keep the diff reviewable. Readability goals do not grant an unlimited refactoring budget.

Who should read it now

I recommend the book to developers who can already implement functions, follow calls and write simple tests, but struggle to explain design decisions during review. A small existing project provides enough material for questioning the advice. Experience with production incidents helps readers recognize hidden effects. Having concrete code to examine matters more than a particular job title.

If you are still learning syntax and debugging, I would postpone a complete reading. Writing small programs and basic tests first gives the discussion a useful foundation. Experienced developers can use the book to reassess team conventions: which rules reduce mistakes, which merely preserve someone's taste, and which overlook the language's ordinary idioms? Reading together is worthwhile when disagreement remains tied to actual examples.

Your next book in the series should follow your current obstacle. If you agree that code needs improvement but want help making small changes, continue with Refactoring. If changing unprotected code is the main difficulty, prioritize Working Effectively with Legacy Code. To challenge whether a decomposition reduces complexity, read A Philosophy of Software Design. These are different roles in a reading plan, and comparing them helps prevent one preference from becoming a universal answer.

A reading plan with observable results

Read one topic at a time. Keep a short record of the problematic code, the reader's question, the proposed change and the expected evidence. Start with an ambiguous name in code you already need to modify. Then try separating a calculation from an external effect. That sequence lets you observe benefits and costs before proposing a repository-wide convention.

For each experiment, ask a colleague to describe inputs, outputs and side effects before and after the edit. Check the same behavior cases, including relevant boundaries and failures. Record anything that became worse, such as extra navigation, another interface or difficulty locating a rule. An honest account of those costs is more informative than declaring the result "clean."

My verdict is favorable when the book is read this way. Clean Code supplies useful vocabulary for discussing maintenance and directs attention toward small decisions that accumulate cost. Its value falls when heuristics become context-free orders. Read it with an editor and a project open, ready to explain both an improvement and a disagreement. The worthwhile result is a team that can justify changes more precisely.