Oh My Learning

Boundaries and the Humble Object Pattern

clean-architecture/09 senior drafted · 8 min read

Clean Architecture (Robert C. Martin), Chapters 17, 24

Prerequisites clean-architecture/08

Boundaries and the Humble Object Pattern#

TL;DR#

Not every architectural boundary needs the full Dependency Rule ceremony — Martin distinguishes when a boundary is worth drawing (and defending with interfaces) from when it's premature. Where a boundary genuinely is needed, but one side is inherently hard to test (UI rendering, database access), the Humble Object pattern splits that side into a "humble," barely-tested wrapper and a fully-testable, logic-rich counterpart behind a clean interface — pushing all real logic away from the untestable part.

The idea#

clean-architecture/08 established how to structure a dependency-inverting boundary; this lesson addresses two remaining, practical questions: when is a boundary actually worth drawing (since every boundary has a real structural cost), and what specifically do you do with the genuinely, inherently hard-to-test code that inevitably sits at the very edge of a system (rendering pixels to a screen, writing bytes to a database driver) — code that can't simply be "made testable" the way most application logic can.

How it works#

When to draw a boundary — the cost/benefit test#

Martin is explicit that boundaries aren't free — each one requires an interface, a plugin point, and the discipline to maintain the Dependency Rule across it, all of which cost real development time and add real indirection. The decision to draw a boundary should be driven by the same "which decisions are volatile or expensive to reverse" logic as clean-architecture/01's framing: draw a boundary specifically where you anticipate genuine volatility or a genuine need for independent evolution (a database that might be swapped, a UI that might need a second delivery mechanism, an external service that might change vendors) — not reflexively around every possible axis of variation, echoing this whole subject's repeated caution (via pragmatic-programmer/05, philosophy-of-software-design/05, clean-code/12) against speculative, unjustified abstraction.

Worked example. A small internal admin tool with one database, one UI, and no credible plan to ever swap either, doesn't need the full ceremony of an OrderRepository interface with a swappable implementation — direct, simple database access from the application logic might be entirely appropriate there, deferring the boundary until (and unless) real evidence of a need to swap actually appears. A payment-processing core embedded in a product expected to support multiple database backends across different customer deployments, by contrast, clearly warrants the full boundary treatment from day one, because the volatility is real and known upfront, not merely hypothetical.

The Humble Object pattern — isolating what genuinely can't be tested#

Some code is inherently, structurally hard to unit test no matter how it's organized — code that renders pixels, code that makes a live network call, code that directly manipulates a database connection's low-level protocol. The Humble Object pattern's specific technique: split such code into two pieces at the boundary. The humble piece contains only the genuinely untestable mechanics (the actual render() call to a UI toolkit, the actual execute() call to a database driver) and is kept so minimal and simple that it needs little or no testing to trust — its correctness is nearly self-evident from inspection, because there's almost nothing in it to get wrong. All genuine logic (formatting decisions, validation, business rules about what to display or persist) is pulled out into a separate, fully-testable class that the humble object merely calls.

Worked example — applying Humble Object to a UI view.

# Before — logic entangled with untestable rendering
class OrderView:
    def render(self, order):
        display_name = order.customer.name.upper() if order.is_priority else order.customer.name
        color = "red" if order.is_overdue else "black"
        screen.draw_text(display_name, color=color)   # the untestable part

# After — Humble Object split
class OrderPresenter:                       # fully testable — no rendering, pure logic
    def present(self, order):
        display_name = order.customer.name.upper() if order.is_priority else order.customer.name
        color = "red" if order.is_overdue else "black"
        return {"text": display_name, "color": color}

class OrderView:                            # humble — nearly nothing to get wrong
    def render(self, order):
        data = OrderPresenter().present(order)
        screen.draw_text(data["text"], color=data["color"])

OrderPresenter can now be tested exhaustively (boundary conditions, priority/overdue combinations) with zero screen-rendering involved at all — directly resolving code-complete/13's boundary-testing goals for logic that would otherwise have been trapped inside untestable rendering code. OrderView remains genuinely humble — so simple that a bug in it would almost certainly be caught by casual visual inspection, making its lack of dedicated unit tests an acceptable, deliberate trade-off rather than a gap.

Humble Object as a specific application of "Different Layer, Different Abstraction"#

This pattern directly connects to philosophy-of-software-design/07's pass-through-layer discussion, but with an important distinction: the humble object here is essentially a "pass-through" in the sense of containing little logic of its own — but unlike philosophy-of-software-design/07's pass-through smell (which flags unnecessary layers adding no value), this pass-through is deliberately, valuably minimal specifically because it isolates genuinely untestable mechanics from genuinely testable logic. It's not a smell here — it's the pattern working exactly as intended, and the two lessons' apparent tension is resolved by recognizing the humble object's specific, deliberate purpose (testability isolation) rather than judging it purely by "does this layer add transformation value."

Where Humble Object commonly applies across a system#

Beyond UI rendering, the same pattern recurs at nearly every genuinely untestable boundary: database gateways (a "humble" class that just executes a pre-built query, versus a fully-tested class that builds the query and interprets results), external API clients (a humble HTTP-call wrapper versus a fully-tested class that constructs the request and parses the response), and test-harness adapters generally — anywhere a genuinely thin, hard-to-avoid untestable seam meets substantial logic that can and should be tested.

Pros#

  • Concentrates untestable risk into the smallest possible, nearly-trivial-to-verify-by-inspection surface, rather than letting untestable mechanics and testable logic remain entangled.
  • Enables comprehensive, fast unit testing of the genuine logic (formatting, validation, business rules) that would otherwise be trapped and untested inside rendering/I/O code.
  • The cost/benefit framing for when to draw a boundary prevents the Dependency Rule's full ceremony from being applied reflexively everywhere, regardless of actual need.

Cons#

  • Deciding a boundary isn't yet needed is itself a bet that can be wrong — if volatility does materialize later without a boundary in place, retrofitting one is a real, sometimes substantial refactoring effort (echoing refactoring/11's big-refactoring techniques).
  • The Humble Object split adds an extra class and a translation step (as in the OrderPresenter/OrderView example) that's disproportionate for genuinely trivial rendering/I/O code with negligible embedded logic.
  • Deciding exactly how much logic to pull out of the "humble" side versus leave in it requires judgment — pulling out too little leaves real, valuable logic untested; pulling out too much can make the humble side's remaining glue code awkwardly fragmented.

Alternatives#

  • Integration/end-to-end testing of the humble object directly, accepting its slower, less isolated nature — a reasonable complement (not a replacement) to unit-testing the extracted logic, providing some coverage of the humble object's actual, real-world behavior.
  • UI testing frameworks with record/replay or snapshot capabilities — a different way to gain some confidence in rendering-heavy code without fully applying Humble Object's logic-extraction discipline, trading some precision for less structural change.
  • Accepting untested, humble-by-default glue code without formalizing the pattern — many codebases achieve a similar practical outcome informally, without explicitly naming or deliberately designing for the Humble Object pattern, though often less consistently than a deliberate application would.

When to use it#

Draw a boundary specifically where genuine, credible volatility exists (per the cost/benefit test), not reflexively everywhere. Apply Humble Object specifically at any boundary where one side is inherently, structurally hard to unit test (rendering, low-level I/O), to isolate and preserve the ability to thoroughly test the logic adjacent to it.

When NOT to use it#

Don't draw a full boundary (interface, swappable implementation) for a dependency with no credible volatility or reuse need — that's the exact speculative-abstraction cost this whole subject repeatedly warns against. Don't apply Humble Object's split to genuinely trivial rendering/I/O code with no meaningful embedded logic worth extracting and testing separately.

Key takeaways / mental model#

Before drawing a boundary, ask: "is there real, credible volatility here, or am I guessing?" Where a boundary meets code that's inherently hard to test, split it: push every bit of genuine logic into a fully-testable class, and leave the boundary-touching side so minimal that its correctness is nearly self-evident by inspection alone.

Self-check questions#

  1. Using the OrderView/OrderPresenter example, explain precisely what logic was extracted and why the remaining OrderView doesn't need extensive dedicated unit tests.
  2. Describe a boundary in your own codebase that was drawn prematurely, without real volatility ever materializing. What was the cost of that premature boundary?
  3. Why does the Humble Object pattern's "pass-through" appearance not count as philosophy-of-software-design/07's pass-through-layer smell? What's the key distinguishing factor?
  4. Identify a piece of code in your own experience that mixed genuinely untestable mechanics with testable logic, and sketch how you'd apply Humble Object to separate them.

References#

  • Clean Architecture: A Craftsman's Guide to Software Structure and Design (Robert C. Martin), Chapter 17: "Boundary Anatomy" and Chapter 24: "Partial Boundaries" (Humble Object section).