Stoppability in Code Design

The Small Change That Isn't

You've been asked to add a new refund status: NO_REFUND_REQUIRED. When it's set, no money should be returned to the customer. It sounds like a small change.

You start where the status is set. You search for Refund.setStatus() and find one call site. The value comes from the front end, and it's saved correctly. That part is straightforward.

Then the next question shows up: Where is this status actually used? You search for Refund.getStatus(). Twelve results. Halfway through them, you find a place that returns money to the customer. You could add the condition there and call it done, but you hesitate.

You've found a place to change. The harder part is deciding whether it's the only place that matters.

• Is this the only place refunds happen?
• Is refund status interpreted somewhere else?
• Will another workflow be affected?
• Have I seen enough to stop?

The change looked easy. But you still don't know whether you've found everything that matters or what else this change might affect. You hesitate because stopping might be irresponsible.

In many codebases, the hard part is not writing the change. It's knowing when you understand enough to make it.

That moment of hesitation points to a quality of software design that doesn't get named very often: stoppability.

What Stoppability Is

Even after you've found the likely place and understood the code there, one question often remains:

Have I seen enough to stop searching?

Stoppability is the degree to which a system helps developers reach justified confidence that they have seen enough to make a change with acceptable risk.

This isn't certainty. It means the system gives enough evidence that more searching is unlikely to uncover anything that would materially change the work. A developer with enough confidence can stop because the remaining risk looks acceptable, not because all risk has been eliminated.

That threshold depends on the task. Changing a label in the UI needs less evidence than modifying a refund workflow, changing security logic, or introducing new behavior in a critical path. Higher-risk changes require stronger evidence before stopping becomes rational.

Readability Still Matters

Stoppability assumes developers can understand the code they've already found. If the local code is confusing, they may keep searching because they don't trust their interpretation. (That local readability problem is explored in Readability is a Performance Constraint.)

Real Systems Are Uneven

Stoppability is local, not global. Most systems are uneven. Some areas are strongly stoppable: boundaries are clear, behavior is localized, and side effects are visible. Other areas are weakly stoppable: logic is scattered, naming is vague, and changes may spread in unclear ways.

Unavoidable vs. Extraneous Exploration

Some exploration is unavoidable. Real domains contain genuine complexity, and some architectures increase exploration as a tradeoff of their design. Distributed systems and event-driven workflows often require broader investigation.

We can't eliminate exploration, but we can reduce extraneous exploration. Extraneous exploration comes from design choices that add uncertainty beyond what the domain requires:

• weak naming
• inconsistent structure
• scattered logic
• hidden side effects
• broken boundaries

Because those costs come from structure, not architecture or domain complexity, they can often be reduced.

Why Search Continues

Search often continues even after the likely place to change is found because two uncertainties are still unresolved.

Uncertainty #1: Where Else Is This Behavior?

After finding what looks like the right place to make a change, developers still need to answer:

Have I found all the relevant locations, or could important logic exist somewhere else?

Stopping becomes rational when other locations are no longer plausible enough to justify more searching.

Signals that strengthen location evidence:

• feature-oriented boundaries
• descriptive names
• consistent structure
• shared vocabulary
• clear ownership of behavior

These signals help in two ways: they make likely locations easier to find, and they make unlikely locations easier to dismiss. When those signals are missing, many other places remain plausible candidates, so search continues.

Uncertainty #2: What Else Will This Affect?

Finding the right place isn't always enough. Developers also need to answer:

What else could this change affect?

A developer may know exactly where to edit the code, yet still keep searching because the consequences of the change are unclear.

Stopping becomes rational when likely effects are visible, bounded, and understandable.

Signals that strengthen propagation evidence:

• visible dependencies
• explicit workflows
• bounded side effects
• clear downstream paths

These signals make it easier to see what might break before you change anything. When they are absent, more investigation is often justified.

How Location and Propagation Combine

Most systems contain a mix of strongly stoppable and weakly stoppable areas. These two uncertainties create four common working experiences.

Location Evidence	Propagation Evidence	Developer Experience
Low	Low	I'm still searching, and I still don't understand the risk.
High	Low	I know where to edit, but I don't know what I'll break.
Low	High	I understand the likely impact, but I'm not sure I found all the places that matter.
High	High	I can move quickly with enough confidence.

Example: Two Refund Systems

Let's go back to the NO_REFUND_REQUIRED example and compare the experience in two systems.

A System That Keeps You Looking

You search for a RefundStatus enum and can't find one. You start searching for individual refund statuses and find a mix of magic strings and individual constants in classes like CustomerService, OrderService, NotificationService, and others. Each class has some refund-related logic in it. Some overlaps; some is unique.

Now the task is no longer just changing behavior. You're reconstructing the refund system from a pile of search results.

You find one place that returns money to the customer and add your condition there, but stopping still feels premature. The system has not given enough evidence that you found every relevant location or that the change won't create additional effects somewhere else. Continued search still makes sense.

Why Search Continues

• Location: Refund behavior has no clear home, so many places remain plausible.
• Propagation: Dependencies and downstream effects are unclear, so impact is hard to predict.

A System That Lets You Stop

You find a RefundStatus enum and add your new NO_REFUND_REQUIRED value to it. You search for references to RefundStatus and see most of them inside this package:

refunds/
  RefundOrchestrator
  RefundPolicy
  RefundStatus
  ...

The package structure, shared enum references, and small number of outlying search results are evidence that refund behavior is mostly concentrated rather than scattered across the system.

You quickly check the references outside that package to understand the likely downstream effects. One or two related updates are needed, but the available evidence suggests the consequences are limited and understandable.

You open RefundPolicy. There are many rules, but the code is readable. You find where money is returned to the customer and add your conditional check there.

You haven't searched the entire codebase. You stop because the available evidence suggests more searching is unlikely to change your implementation. Stopping is rational.

Why Search Stops

• Location: Refund behavior has a believable home, and references reveal the additional places likely to matter.
• Propagation: Likely effects are visible, bounded, and easier to reason about.

Why This Becomes Expensive

Weakly stoppable systems impose a hidden cost before a change is finished: developers spend extra time and mental effort resolving uncertainty. That cost shows up as:

• small changes turning into long investigations
• reading and discarding many irrelevant files
• tracing possible side effects across the codebase
• slower code reviews because completeness is unclear
• more interruptions to ask experts for confirmation
• extra manual testing to compensate for low confidence

Repeated across a team, these costs increase cycle time.

Weak stoppability also increases the risk of bugs. Developers may stop too early and miss relevant behavior, or work with incomplete understanding because they didn't realize they needed to search further.

Over time, these areas become places people avoid. Knowledge concentrates in the few developers willing to deal with the uncertainty, and those people become bottlenecks.

Strongly stoppable systems reverse that dynamic. Developers can make progress with justified confidence, ownership spreads, and changes get finished faster.

Stoppability as a Design Goal

Stoppability is about giving developers enough evidence to stop searching rationally. It is not about guaranteeing certainty. Software systems are rarely that clean, and experienced developers know there is always a chance that relevant behavior exists somewhere unexpected.

In a well-designed system, finding one answer changes what you believe about that part of the system. A clear boundary, a trustworthy naming pattern, a consistent architectural rule, or an obvious ownership model lowers the probability that important behavior is hiding elsewhere. Search becomes narrower, cheaper, and eventually unnecessary.

In a poorly designed system, the opposite happens. Every answer creates new plausible places to check. Logic is scattered, patterns are inconsistent, and boundaries can't be trusted. Developers keep reading, not because they're perfectionistic, but because that part of the system has not earned their confidence.

This matters because most of software development isn't writing code. It is locating behavior, understanding consequences, reviewing changes, debugging problems, and deciding when enough investigation has been done to move forward. Systems that never let people stop turn routine work into chronic cognitive overhead.

Good design does more than organize code. It changes what developers can rule out. It gives them enough confidence that they have seen enough to act under uncertainty. That is what makes a growing system sustainable.

In my final post, Understandable Systems Generate Evidence, I'll pull these ideas together and look at how understandable systems preserve the evidence developers need to find behavior, trace consequences, and change code with justified confidence.

AI was my editor, but these ideas are my own.

---

This article is part of a broader series exploring how code structure, navigability, and cohesion align with cognitive limits.

If you're interested in the deeper dive, the full series is here:
Designing Code for Human Brains