DEV Community: Christie Cosky

Understandable Systems Generate Evidence: How structure helps developers change code with justified confidence

Christie Cosky — Tue, 09 Jun 2026 16:00:00 +0000

(The following example is fictionalized.)

A notification template feature shipped six months ago. It let each tenant customize the messages sent to their own customers without requiring a back-end change every time the wording changed.

The code reviewer could tell the design was hard to follow, especially the path from template to rendered value. But "this is hard to follow" is difficult to turn into a concrete objection when the feature works, the tests pass, and nothing is obviously unsafe or wrong. The design risk was real, but there wasn't an obvious bug to point to.

QA signed off, and the feature went into production.

Then a bug report came in: one customer had received a notification containing another customer's information. Somewhere in the notification pipeline, the system was leaking PII.

At first, the fix sounded small: make sure notifications only render data belonging to the intended recipient.

Then the assigned developer, who wasn't the original author, started looking for the place to make the fix.

The templates were stored in the database. There were six template types, and each one populated its real values in a different part of the codebase. Some values came from customer-facing records, some came from internal workflow state, and some came from template-specific logic. The placeholder-to-value mapping lived somewhere else. Email and SMS channels shared part of the rendering path, but not all of it.

Before the developer could decide where to fix the leak, they had to answer a more specific set of questions:

Which placeholder rendered the wrong value?
Where did that value come from?
Which template types could use that placeholder?
Did email and SMS resolve it the same way?
What evidence would show that the leak was fully contained?

The system was hard to change because it made the behavior hard to understand.

What the developer needed was not just "clean code." They needed trustworthy signals they could use as evidence to answer harder questions: where the behavior lived, which paths shared it, what data was allowed to flow through it, and when their search was complete enough to make a safe change.

In a situation like this, designing code that runs is not enough. The system also has to preserve enough evidence for the next developer to understand and change it safely.

Good Design Generates Evidence

The rendering bug exposed a deeper problem: the system did not make the notification path traceable enough to change safely. The developer needed to understand how a template became a rendered message before they could decide where a safe fix belonged.

That happens a lot in software development. Often the hard part isn't the edit itself. It's understanding enough of the surrounding behavior to know where the change belongs and whether it is safe.

To build that understanding, the developer looked for signals in the codebase that they could trust.

A package name can give the developer a credible place to start. A class name can signal what kind of logic belongs inside. A shared enum can show which concepts are related. An explicit dependency can make side effects easier to see. A test can name behavior the system promises to preserve.

But those signals are not automatically evidence. A package name can be a catch-all. A class can drift from its original purpose. A test name can describe one case while actually testing another.

A signal becomes evidence when the code keeps the promise the signal makes. That's when the developer can reason from it.

Good design doesn't just make code cleaner. It makes the system's signals trustworthy enough for the developer to reason about where behavior lives, what belongs together, which paths are unlikely to matter, and how far a change might travel.

The signals a developer relies on change over the course of an investigation. Early on, they need help locating behavior and parsing logic. Later, they need help tracing consequences and deciding whether the remaining risk is small enough to stop searching.

Understandability Has Layers

Developers do not move through these layers in a neat sequence. They may start by searching, open a file, realize it is the wrong place, trace a dependency, and search again. But the layers describe different kinds of signals the system provides as the developer builds enough understanding to decide what can be trusted.

Perception: Can I Parse What I'm Looking At?

Before the developer can reason about the notification leak, they have to parse the code in front of them. Shape, grouping, indentation, spacing, and hierarchy show them what belongs together and where one idea ends.

If the rendering code is a dense block of conditionals, placeholder substitutions, and channel-specific branches, the developer has to reconstruct its shape before they can investigate the leak. They are spending attention on parsing before they can spend it on analysis.

When this layer fails, the developer spends cognitive effort reconstructing the shape of the code before they can reason about where the logic might be wrong.

Local Reasoning: Can I Hold the Relevant Ideas in Mind?

Local reasoning is what happens after the developer has found a piece of code and starts asking whether they can understand what that unit is responsible for.

A method named renderTemplate sounds narrow. It makes a claim about what kind of reasoning belongs there.

But if the method implements template loading, recipient lookup, tenant rules, placeholder resolution, channel formatting, missing-value behavior, and skip conditions inline, the body does not keep that promise. Each step may be necessary somewhere in the rendering workflow, but they don't belong at the same level of detail.

Good boundaries reduce cognitive load because they tell the reader what kind of reasoning belongs inside them. Rendering, recipient lookup, tenant rules, channel formatting, and delivery decisions require different mental frames. When one method mixes those frames at the implementation level, the reader has to hold too many mental models at once.

When this layer fails, reading turns into mental juggling.

Navigation: Can I Find the Right Place to Start?

In the notification bug, the developer could not start from "the rendering workflow" because template storage, placeholder mapping, data lookup, and channel-specific behavior were scattered across the system.

A navigable system makes the first plausible place easier to find, and it makes unrelated places easier to rule out. A notifications/templates package is a signal. It doesn't prove the leak is there, but it gives the developer a more credible starting point than TenantController, CustomerService, or MessageUtils.

Good design doesn't just help developers find the right places to change; it also helps them rule out the wrong ones sooner.

When this layer fails, too many places stay plausible for too long.

Propagation: Can I Trace Where This Change Can Travel?

Once the developer finds one place where the wrong data enters a template, the next question is where that value can travel. Does the same placeholder appear in both notification channels? Does a fix in the placeholder renderer affect both channels, or only one of them?

Good design makes propagation visible and bounded. If email and SMS both pass through the same placeholder renderer, the developer can see that a fix in the shared path may affect both channels. If they use separate channel-specific formatters, the developer can see that each path may need to be checked separately. The structure does not decide the fix for them, but it shows where the change can travel.

Hidden listeners, framework hooks, database triggers, and distant side effects may be necessary, but they make the change path harder to see.

When this layer fails, every edit carries an unknown blast radius.

Stoppability: Can I Know When I've Seen Enough?

Even after the developer understands where the data can travel, one question remains: have they checked enough to make the change safely?

Stoppability is where enough trustworthy signals accumulate to justify stopping the search. Clear names, bounded responsibilities, visible dependencies, consistent patterns, and trustworthy tests combine into a confidence threshold. When those signals point in the same direction, stopping becomes justified. When they conflict, continued searching is rational.

When this layer fails, small tasks become open-ended investigations.

Confidence Comes When Signals Agree

One trustworthy signal rarely carries the whole investigation.

A notifications/templates package may suggest where template behavior belongs, but it is not enough by itself. The developer still needs to know whether placeholder names are defined consistently, whether template types share the same rendering path, whether email and SMS share the risky behavior, and whether the tests cover the cross-tenant rule.

Confidence comes when those answers point in the same direction. When they do, the developer can start in the most plausible place, dismiss unrelated paths sooner, trace likely side effects, and stop when the remaining risk is small enough to act.

When the signals conflict, confidence becomes harder to justify. The package suggests one home for the behavior, but a relevant-looking class sits somewhere else, and several template types only appear as magic strings outside the package. The test names claim to cover cross-tenancy, but the assertions prove something else. The system may still run, but the developer doesn't have a coherent interpretation they can trust.

That is the difference between local readability and system understandability. Readable code is easier to parse. Understandable systems produce enough trustworthy evidence for developers to make justified decisions under uncertainty.

Understandability Depends on Trustworthy Signals

Time is the stress test for all of these layers.

The notification feature shipped six months earlier. The original author has moved on. The design tradeoffs and assumptions behind the implementation are no longer fresh in anyone's mind. The next developer has to reconstruct the behavior from the signals the system still provides.

Some signals are weak from the start. Entity-based structures like TenantController and CustomerService may look organized, but they often give poor evidence about where feature behavior lives.

Other signals lose trust over time. Formatting drift makes structure harder to recognize. Naming drift makes search less trustworthy. Boundaries weaken when classes absorb behavior their names no longer explain. Hidden dependencies make change paths harder to predict. One-off exceptions make it harder to know whether the behavior you found represents the rule or just another special case.

The drift usually happens through changes that look harmless in isolation. One duplicated placeholder mapping. One special case. One class with a name broad enough to hold anything. Each one makes the system a little less trustworthy as a guide for the next developer.

That is how "hard to follow" becomes operational risk. Sometimes the structure was misleading from the beginning. Sometimes it eroded slowly. Either way, the system doesn't provide reliable signals about its own behavior, and the next developer making a change is more likely to miss a path, misunderstand the logic, or introduce a bug.

Understandability has to be preserved over time. When it's not, confidence gets harder to justify.

AI Raises the Stakes for Trustworthy Evidence

AI-generated code can accelerate that drift. It can generate plausible signals very quickly, but plausible signals are not the same as trustworthy evidence. A generated class name can make a precise-sounding claim without preserving a real boundary. A generated test can name an important behavior without proving it.

Reviewing AI-generated code means checking more than correctness. It means checking whether the names, boundaries, and tests are telling the truth.

If AI adds a TenantScopedTemplateRenderer and a test named whenTenantDataCrossesBoundary_rejectsValue, those names make claims about where behavior lives and what behavior is protected. The reviewer has to decide whether the code actually keeps those promises. The class boundary may keep tenant-scoped rendering separate from recipient lookup and channel formatting, or it may only rename a workflow whose responsibilities are still mixed together. The test may prove the cross-tenant rendering rule, or it may be checking something else entirely.

Code reviewers of AI-generated code should not ask only whether the new structure looks cleaner. They should ask whether it gives the next developer better evidence to reason from.

If the names, boundaries, and tests preserve trustworthy evidence, AI can support understandability. If they only create the appearance of structure, humans still have more code to verify and reinterpret before they can trust it.

How This Changes Code Review

Understanding what makes a system understandable gives code reviewers better language. Instead of stopping at "This is hard to follow," they can point out which kind of evidence the design is failing to provide:

Perception: Is the code shaped clearly enough to parse?
Local reasoning: Does each boundary contain one kind of reasoning?
Navigation: Can a future developer find where this behavior lives?
Propagation: Are the paths and side effects visible enough to trace?
Stoppability: Can a developer tell when they have checked enough?
Signal agreement: Do the names, boundaries, dependencies, and tests point to the same interpretation?

These questions turn a vague discomfort into something concrete. They do not guarantee a perfect design, but they give reviewers better ways to talk about risk before the risk turns into a bug.

Systems That Remain Understandable

The notification bug is one example of the larger design problem underneath this series.

The path from template to placeholder to data source to recipient was not visible enough for the next developer to reason about quickly under pressure. When something went wrong, the system did not preserve enough evidence for the next person to trace what had happened.

Formatting, naming, boundaries, cohesion, navigability, and stoppability can look like separate concerns, but they all contribute to the same larger goal. Each one either strengthens or weakens the system as a source of evidence for the next developer.

Code has to execute correctly. Long-lived systems also have to preserve evidence for the people who will change them later, after memory has faded, authors have moved on, and the original context is gone.

A system is sustainable when it can keep growing without erasing the evidence future developers need to change it safely.

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

Stoppability in Code Design

Christie Cosky — Tue, 02 Jun 2026 16:00:00 +0000

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

Why Some Codebases Are Hard to Understand: Cognitive Surface Area and the Hidden Cost of System Navigation

Christie Cosky — Tue, 26 May 2026 16:00:00 +0000

Information Foraging: How Developers Navigate Systems

Developers rarely read code from top to bottom. They navigate it. When debugging or extending a system, developers follow cues that suggest where relevant behavior might live, such as:

Directory structure and package names
Class names
Method names
Enums and constant values

Each cue helps answer a constant question during exploration: "Where should I look next?"

This behavior resembles patterns studied in human-computer interaction research. Information Foraging Theory describes how people search for information by following cues that signal where valuable information is likely to be found.

When the cues are strong, developers can quickly eliminate large portions of the system and focus only on relevant areas. When they are weak, developers must explore much more of the system before they can understand the behavior.

Software systems differ dramatically in how much of the codebase developers must explore to understand behavior.

Cognitive surface area describes how much of a system developers must mentally explore to understand or change behavior.

Imagine debugging a refund bug: customers who should receive refunds are not getting them.

You notice a refunds package in the service layer. Inside it is a class named RefundPolicy. You open it. The class contains a single public method and a few helpers, all focused on refund eligibility. Within a few seconds you know you're looking in the right place. Most of the system has already been ruled out. You only had to explore a small portion of the codebase.

Now imagine the same bug in a system with weaker cues.

Packages reveal only architectural layers (controller, service, repository) but not functionality. No classes contain "refund" in their names. A full-text search returns seventeen results scattered across CustomerService, EmailService, OrderService, PaymentService, and ScheduledJobs. Each class is large, and refund-related logic appears in several different places. Instead of quickly eliminating irrelevant areas, you must open and read multiple files just to determine whether they are related to the bug. Much more of the system must be explored before you know you're finally in the right place.

In the first system, the structure provides clear breadcrumbs that guide exploration. In the second, the cues are weak and the developer must wander through the codebase. Breadcrumb systems create strong cues that guide exploration. In mystery meat systems, developers are forced to wander. (I explored this distinction in more detail in Mystery Meat vs. Breadcrumb Systems.)

Search Space: Why Cognitive Surface Area Matters

When debugging or extending code, developers search the system for where behavior lives or should live. For example, when tracking down a bug:

Is it in the front end or the back end?
Which package is it in?
Which class is it in?
Which method is it in?
What state triggered the behavior?

Each question defines part of the search space a developer must explore. The more places a bug could plausibly live, the harder it becomes to narrow the investigation. Good structure narrows it by helping developers rule out large portions of the system quickly.

Large systems aren't necessarily difficult to understand. Systems with large search spaces are. Some systems remain navigable even as they grow, while others become confusing surprisingly quickly.

The difference often isn't size, but cognitive surface area.

When a system has a small cognitive surface area, the path from a question ("Why is this refund failing?") to the responsible code is short. When surface area is large, developers must search much more of the system before they can find the relevant behavior.

Question: "Why did this refund fail?"

Small Surface Area
──────────────────
service/
  refund/
    RefundPolicy

Large Surface Area
──────────────────
service/
  CustomerService
  EmailService
  OrderService
  PaymentService
  ScheduledJobs

I've reviewed files only a hundred lines long that were surprisingly difficult to follow because understanding them required exploring several unrelated concerns. But I've also reviewed files twice that size that were much easier to understand because the structure was predictable and the naming was clear.

The same contrast appears at the system level. I've worked in legacy codebases that were decades old and relatively easy to navigate, and in younger codebases that were much harder. The difference wasn't age or scale. It was how much of the system I had to mentally explore to get my work done.

Four Sources of Cognitive Surface Area

When developers investigate behavior in a system, they must find answers to several questions.

Where should I look?
What concepts do I need to understand?
What patterns does this system follow?
What other components influence this behavior?

These questions correspond to four different ways systems expand the amount of code developers must explore.

Developer Question	Surface Area
Where should I look?	Navigation surface area
What concepts do I need to understand?	Concept surface area
What patterns does this system follow?	Structural surface area
What other components influence this behavior?	Dependency surface area

These four dimensions describe common sources of cognitive surface area within the code itself.

Navigation surface area concerns how many places behavior might live. Structural surface area concerns whether developers can predict where behavior should live.

The dimensions are not entirely independent. Many problems increase several types of surface area at once. The goal of the framework is not perfect categorization, but to highlight the different ways systems become harder to understand.

Each surface area expands for different reasons:

Navigation surface area grows when behavior could plausibly live in many places.
Concept surface area grows when multiple ideas must be understood at once.
Structural surface area grows when the system's organization is unpredictable.
Dependency surface area grows when many components influence the behavior.

When teams say a codebase is "hard to understand," it often means one or more of these surface areas has grown too large.

Some systems naturally have large search spaces because the domain itself is complex. Good architecture can't eliminate that complexity, but it can prevent unnecessary cognitive surface area from accumulating.

Navigation Surface Area

Navigation surface area relates to the question: Where should I look?

It describes how many places a developer might need to search to locate the behavior they are investigating.

When navigation surface area is large, developers must explore many parts of the system before finding the relevant code. When it is small, much of the system can be ruled out immediately.

Layer-Based Package Dumping Grounds

When packages are organized solely by architectural layer (controller, service, repository), package names provide little guidance about where behavior lives. A developer can't rule out files by package and must search across many classes to locate the relevant functionality.

service/
  CustomerService
  EmailService
  OrderService
  PaymentService
  ScheduledJobs

A developer trying to locate refund logic must open multiple classes to determine where it lives. The navigation surface area is large because many files remain plausible candidates.

Compare that to functionality-oriented packaging:

service/
  refund/ 
    RefundOrchestrator
    RefundPolicy 
    RefundProcessor

Now the search space is much smaller. Developers can navigate directly to the part of the system that matches the functionality they are investigating.

Entity God Classes

Some systems organize controller, service, and repository classes around persistence entities. Over time, these classes accumulate many unrelated behaviors associated with that table.

For example:

class CustomerService { 
  calculateLoyaltyDiscount(...) 
  processRefund(...) 
  sendPromotionalEmail(...) 
}

Because many unrelated behaviors accumulate in the same class, developers must search through large files to locate the behavior they need.

Compare that with classes organized around specific behaviors:

LoyaltyDiscountCalculator
RefundPolicy 
PromotionalEmailSender

Now the class name itself helps narrow the search space.

Microservices

In distributed systems, navigation begins at the microservice level. Before debugging can begin, a developer must determine which service owns the behavior. Each additional plausible service expands the navigation surface area. If service boundaries are unclear, developers may need to explore several services before locating the relevant behavior.

When service boundaries align clearly with business capabilities, the search space is small. When they don't, the navigation surface area grows.

Concept Surface Area

Concept surface area relates to the question: What concepts must I understand?

It describes how many concepts a developer must hold in mind simultaneously while reading code.

Mixed Responsibilities

Classes with multiple responsibilities force developers to switch between conceptual frames while reading the code.

The problem is not that a piece of code performs several steps. Many methods legitimately coordinate a workflow. For example, a method that executes a refund process may validate the request, calculate the refund amount, call a payment gateway, and record the result. Those steps all belong to the same conceptual frame: executing the refund workflow.

Mixed responsibilities appear when a boundary begins to absorb several different kinds of reasoning that do not belong to a single conceptual frame.

For example, a single class or method might contain:

business rules and policy decisions
financial calculations
persistence logic
external API integration details
notification behavior
analytics or auditing decisions

Even if each individual piece of logic is understandable, the reader must constantly switch between different kinds of thinking while reading the code. Instead of reasoning about one idea at a time, the developer must juggle several unrelated concerns simultaneously.

When responsibilities are separated into clearer conceptual units, each piece of code can usually be understood within a single mental frame. This reduces the number of ideas developers must keep in working memory at once and makes the system easier to reason about. (This is how the Single Responsibility Principle protects working memory.)

Unclear Concept Boundaries

Concept surface area also increases when a single concept is scattered across multiple components instead of having a clear home.

For example, refund eligibility rules might appear in several places:

// OrderService 
if (order.isExpired()) { 
  throw new RefundNotAllowedException(); 
}

// PaymentService 
if (order.getAmount().compareTo(MAX_REFUND_AMOUNT) > 0) { 
  throw new RefundNotAllowedException(); 
}

// CustomerService 
if (customer.isFlaggedForFraud()) { 
  throw new RefundNotAllowedException(); 
}

A developer trying to understand refund rules must inspect multiple classes and mentally assemble the full policy from scattered pieces.

Compare that with a centralized design:

RefundPolicy

Now the concept has a clear boundary. Developers know exactly where to look to understand the rules.

Structural Surface Area

Structural surface area relates to the question: What patterns does this system follow?

It describes how predictable the organization of the system is.

In predictable systems, developers can make strong assumptions about where certain types of logic belong. In unpredictable systems, those assumptions break down, forcing developers to inspect more of the codebase to confirm where behavior lives.

Structural surface area grows when developers can't rely on consistent structural rules about where certain kinds of logic belong.

Inconsistent Structural Patterns

Structural surface area increases when similar problems are solved using different structural patterns.

For example, validation might sometimes appear in a *Validator class, but other times be embedded directly inside a *Service class.

// Pattern A 
CustomerValidator 

// Pattern B 
CustomerService.validateCustomer(...)

Now developers cannot rely on a single structural rule to locate validation logic. They must remember that validation may appear in multiple structural forms.

In systems with consistent patterns, developers quickly learn where different kinds of logic belong.

Inconsistent Naming Patterns

Predictable naming patterns reinforce structural expectations, because they act as structural cues developers rely on to predict where logic belongs.

Consider the following class names:

CustomerService 
CustomerManager 
CustomerHelper 
CustomerUtils 
CustomerProcessor

The roles of these classes are unclear, making it difficult to infer what logic belongs in each one.

Compare that with names that constrain responsibility:

CustomerCreditLimitValidator 
CustomerRefundEligibilityPolicy 
CustomerLoyaltyPointsCalculator

These names create structural expectations about what logic belongs in each class. For example, CustomerCreditLimitValidator clearly suggests that only credit limit validation belongs there.

Clear naming reduces structural surface area because developers can predict where logic should exist.

Structural Drift

Structural surface area can also grow gradually as teams introduce exceptions to previously clear patterns.

Imagine a system with a clear place for refund eligibility rules:

RefundEligibilityPolicy

Later, a special case appears in unrelated code:

if (order.getCustomerType() == VIP) { 
  return true; // vips always get refunds
}

Then another rule is implemented separately:

VipRefundPolicy

Now refund eligibility logic exists in multiple structural forms:

a central policy class
inline conditional logic
a special-case policy class

Developers can no longer infer where new rules should live because the structural pattern has broken down.

Dependency Surface Area

Dependency surface area relates to the question: What other components influence this behavior?

It describes how many other parts of the system must be understood in order to reason about the code being examined.

When behavior depends on many other components, developers must explore those dependencies before they can confidently understand or modify the code.

Distributed Workflow Chains

Dependency surface area increases when behavior propagates through multi-step workflows across microservices.

A developer might change this code in an order service:

order.setRiskCategory(calculateRiskCategory(order));

That looks local. But the risk category may later be read by a saga orchestrator, passed to a payment service, and then used by a fraud service to decide whether the transaction should be rejected.

The dependency is not visible where the value is first written. To understand the impact of the change, the developer must trace how that data is consumed across several downstream steps.

The more behavior depends on these distributed workflow chains, the larger the dependency surface area becomes.

Implicit Side Effects

Dependency surface area also increases when code triggers behavior that is not visible where the call occurs.

For example:

orderRepository.save(order);

This appears to simply persist the order. But it might also trigger:

inventory updates
fraud checks
event publication
email notifications

If these side effects occur through framework hooks, triggers, or event listeners, they may not be visible at the call site.

Understanding the behavior requires knowledge of interactions that occur elsewhere in the system.

Event Chains

Event-driven systems can expand dependency surface area. This trade-off is often intentional (event architectures provide flexibility and decoupling), but they also make system behavior harder to reason about.

Publishing an event:

eventBus.publish(new OrderPlacedEvent(order));

might trigger several consumers:

InventoryService
EmailService
BillingService
AnalyticsService

To understand the full consequences of placing an order, developers must track how the event propagates through the system.

Long event chains make it harder to predict the downstream effects of a change.

These dimensions describe four different ways systems increase the amount of code developers must explore to understand behavior.

Cognitive surface area grows when developers must explore more of the system to understand behavior.

Mechanical Size vs Cognitive Surface Area

We usually measure system size mechanically: lines of code, binary size, runtime performance. Those metrics say very little about how difficult a system is to understand. Two systems can contain the same number of lines of code but impose very different cognitive demands. What matters is how much of the system developers must explore to understand behavior.

Human working memory is limited. When developers must load too many unrelated concepts at once, reasoning slows and mistakes become more likely.

A large system can still have a small cognitive surface area if developers can quickly navigate to the code that contains the relevant concepts. When boundaries are clear and structure is predictable, developers only need to load the concepts relevant to the task at hand into their working memory.

A large system with a small cognitive surface area typically has:

Clear boundaries between packages, classes, and methods
Predictable structure
Strong navigation cues

A large system with a large cognitive surface area tends to have:

Scattered logic
Inconsistent patterns and unpredictable structure
Hidden dependencies

Traditional code complexity metrics focus on control flow inside individual functions — how difficult the code is to simulate mentally. Cognitive surface area focuses on how much of the system developers must explore to understand behavior — how difficult the system is to navigate and reason about.

How Architecture Shrinks Cognitive Surface Area

Many well-known design principles in software engineering reduce one or more dimensions of cognitive surface area:

Practice	Primary Surface Area Reduced
Domain-oriented package organization	Navigation surface area
Clear, descriptive naming	Navigation surface area
Single Responsibility Principle	Concept surface area
Small, focused methods	Concept surface area
Consistent architectural patterns	Structural surface area
Predictable naming conventions (`Validator`, `Calculator`)	Structural surface area
Loose coupling	Dependency surface area
Dependency injection	Dependency surface area

Individually, these practices can feel like stylistic preferences or architectural taste. Collectively, they shape how easy a system is to explore and reason about. This is why large codebases can still feel easy to navigate, while small systems can feel overwhelming when their structure is unclear.

Good architecture helps minimize how much of the system developers must explore to locate, understand, and reason about behavior.

Why Cognitive Surface Area Slows Teams Down

Cognitive surface area directly affects engineering velocity because it determines how much of the system developers must explore before they can safely modify behavior.

Large surface area means developers must explore more of the system before they can safely modify behavior. This slows debugging, pull-request review, onboarding, refactoring, and incident response.

Because a large portion of engineering time is spent understanding existing code rather than writing new code, these exploration costs dominate day-to-day development work. These delays compound across the team: onboarding takes longer, pull requests require more context to review, and incidents take longer to diagnose. When developers must search more of the system, load more concepts into working memory, navigate inconsistent patterns, or reason about hidden dependencies, progress slows. (I explored how readability constrains performance in Readability is a Performance Constraint.)

Reducing cognitive surface area shortens the path between seeing a problem and understanding the code responsible for it.

AI Is Expanding Cognitive Surface Area Faster

Traditionally this growth happened slowly. AI changes that dynamic by dramatically reducing the cost of producing code. Systems can now grow faster than teams can control the cognitive surface area they create.

AI-generated features introduce new classes, modules, and services rapidly, often based on local context rather than system-wide architectural patterns unless those patterns are explicitly reinforced. If the surrounding code already contains structural problems, like inconsistent patterns, overloaded abstractions, or unclear boundaries, AI will often reproduce them.

Without guardrails, AI can unintentionally increase:

navigation surface area (more places code might live)
concept surface area (more responsibilities mixed together)
structural surface area (more inconsistent patterns)
dependency surface area (more hidden interactions)

The result is systems that grow quickly but become progressively harder to understand.

AI makes it easier to produce code, but it does not automatically make systems easier to navigate. (I previously explored how AI makes readability more important, not less.)

Diagnosing Cognitive Surface Area

When a codebase feels difficult to understand, the difficulty usually traces back to one or more of these questions:

Navigation surface area:

Do I know where the relevant behavior lives?
Are there many plausible places to check?

Concept surface area:

How many different ideas are mixed together in this code?
Do I have to hold multiple responsibilities in mind at once?

Structural surface area:

Does the system follow predictable patterns?
Can I guess where similar logic should exist?

Dependency surface area:

What other components influence this behavior?
Are those dependencies visible from the code in front of me?

When several of these questions are difficult to answer, developers must explore more of the system to understand what it is doing.

Managing Cognitive Surface Area

The cheapest way to manage cognitive surface area is to prevent it from growing in the first place. But most teams inherit systems that already contain large cognitive surface area. In those environments, improvement usually happens gradually.

One approach we used on Taz was to clean as we went. We added a new base package to our monolith where all new code went. Legacy code remained isolated in the old base package. As old features were extended or refactored, they were moved into the new base package. Over time, the amount of legacy code shrunk.

Managing cognitive surface area often involves small improvements applied consistently:

Reduce Navigation Surface Area

Organize packages around functionality, not just architectural layers
Break up packages that contain unrelated functionality
Use clear, descriptive package and class names

Reduce Concept Surface Area

Refactor multi-responsibility classes
Apply the Single Responsibility Principle to new classes
Use names that are fences, keeping related functionality inside and unrelated functionality outside
Break large methods up using helper methods

Reduce Structural Surface Area

Maintain consistent architectural patterns
Use predictable naming conventions
Correct structural drift when introducing new code

Reduce Dependency Surface Area

Limit hidden side effects
Prefer explicit dependencies
Limit dependencies across unrelated modules

AI can help with many of these tasks. Teams can encode rules into agent instructions or automated code reviews. AI can assist with refactoring, renaming, and decomposing large classes. Used carefully, AI can reduce cognitive surface area instead of expanding it.

The Goal: Keep the System Navigable

Software systems inevitably grow. But they don't have to become unnavigable as they grow. The goal of good architecture is not only to control complexity inside individual components, but also to keep the cognitive surface area of the system manageable over time.

The real difficulty of a system isn't its raw complexity. It's how much of the system developers must explore before they understand it.

Reducing cognitive surface area helps you find the code. It limits how much of the system you need to search and understand just to locate behavior.

But finding the code is not the same as feeling confidence that it's safe to change. You can reach the right place in the system and still hesitate, still wondering what you might be missing.

Navigation tells you where to go. It doesn't tell you whether you understand enough to make a safe change — and that's the gap I'll explore next in my next article, Stoppability in Code Design.

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 Systems for Human Brains

Why AI Makes Readability More Important, Not Less

Christie Cosky — Tue, 19 May 2026 16:00:00 +0000

Software development has always had an asymmetry: code can be written faster than it can be understood.

Code is written once but read repeatedly during reviews, debugging sessions, refactors, and production incidents. The real constraint has always been understanding code rather than typing it.

AI dramatically widens that asymmetry. Tools like GitHub Copilot and Claude Code can generate thousands of lines of code in minutes, but the speed at which humans understand code hasn't changed.

Before AI, the speed of writing code naturally constrained how quickly systems could grow. AI removes much of that friction. But human comprehension speed hasn't changed. Systems can now grow faster than teams can understand them — or keep them coherent.

The asymmetry isn't new, but the magnitude is.

Systems Can Now Grow Faster Than Teams Can Understand

Discussions of AI-generated code often focus on correctness or "AI slop." That risk is real. But a larger risk is structural: how quickly disorder can accumulate as systems grow faster than humans can maintain them.

AI removes much of the friction from writing code. AI can generate large portions of features from a handful of prompts. But every line of code still has to be read, reviewed, debugged, refactored, and extended. Even correct code increases cognitive load, because it still increases the amount of code humans must understand.

A messy system with 20k lines of code is annoying. A messy system with 500k AI-generated lines of code becomes extremely difficult to understand.

AI increases code volume while increasing the speed at which structural entropy, like small inconsistencies and duplicated code blocks, can accumulate.

As that entropy grows, so does the system's cognitive surface area: the amount of structure developers must mentally explore to understand the code.

As systems grow faster, the team's mental model can struggle to keep up.

The Bottleneck Shifts

When developers switch to using AI tools, they spend less time manually writing code and more time analyzing AI-generated code:

reviewing it
validating that it actually behaves correctly
integrating it correctly into the system
refactoring it into something readable
aligning it with existing patterns in the codebase

The bottleneck shifts from typing code to understanding, reviewing, and shaping the generated code to fit the system.

As code volume increases, code review becomes more cognitively demanding. Large AI-generated changes increase review fatigue, making it harder for both the author and the reviewer to fully understand and validate every change.

AI Introduces Structural Drift

AI generates code from the local context it sees rather than a full understanding of the system's architecture. As a result, it does not reliably maintain global structural consistency across the system. Small inconsistencies can accumulate across many changes, such as:

slightly different abstractions
duplicate logic
inconsistent naming
subtle architectural drift

Individually, these differences are small. But across hundreds of changes they compound.

Over time, these inconsistencies increase the cognitive entropy — the amount of disorder a reader must make sense of — of the system. The structure becomes harder to recognize. The patterns become less predictable. When patterns become unpredictable, understanding slows down.

Humans Maintain Coherence

In addition to validating correctness, developers must ensure AI-generated code fits the system's existing structure and conventions. This maintains system coherence. By coherence, I mean:

The structure of the new code makes sense
The patterns remain consistent internally and across the system
The boundaries of methods, classes, and packages remain clear
Responsibilities remain understandable
Complexity remains manageable
Naming remains accurate and meaningful
Similar problems are solved in similar ways

Readable code is required to make that possible.

AI does not automatically maintain system coherence. As codebases grow faster through AI code generation, a larger part of the developer's job becomes counteracting structural drift. Without that effort, the system becomes harder to understand over time, even if every individual piece works.

Readable structure allows coherence to survive as the system grows.

AI Can Also Help Maintain Readability

AI can also help with the work of maintaining coherence. With enough context and a human in the loop to validate their proposals, frontier models are surprisingly good at:

structural refactors
naming improvements
package reorganization
large mechanical changes

I've had good results asking Claude Code to analyze an architectural layer of a codebase and propose an updated package and class structure based on the business functionality it detects — adding breadcrumbs for me. (More on using AI to improve a hard-to-navigate codebase in a future article.) It saves time by handling the analysis and tedious cut-and-paste, and the return on investment multiplies every time someone works in that part of the system and benefits from the improved navigability.

The Constraint Hasn't Changed

AI dramatically reduces the cost of producing code. But the fundamental constraint in software development has never been typing. It has always been understanding. Human comprehension speed does not scale with code generation speed.

Whether a system remains understandable depends on its coherence: the consistency of its structure, boundaries, and patterns. Readable structure is what preserves that coherence as a system evolves.

Some companies are experimenting with AI-driven development loops where agents generate specifications, write implementations, run tests, and even review their own changes. In those environments, humans may not read every line of code. But even highly automated systems still rely on humans when something goes wrong. Production incidents, unexpected behavior, and architectural changes require developers to understand what the system is doing and why.

Whether code is written manually, with AI assistance, or through AI-driven development loops, understandable systems are still necessary for the humans maintaining them.

But what actually determines how difficult a system is to understand?

In my next article, I'll go into more depth about cognitive surface area: the property of a system that determines how much of it developers must mentally explore to understand or change behavior.

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 Systems for Human Brains

Why the Single Responsibility Principle Protects Working Memory

Christie Cosky — Tue, 12 May 2026 16:00:00 +0000

In my previous article, Mystery Meat vs. Breadcrumb Systems, I argued that organizing code by feature reduces unnecessary exploration. Feature-based packages make it easier to navigate to the right place in the system.

But navigation alone doesn't produce comprehension. You can open service.pricing immediately and still have no idea what you're looking at. Finding the file only solves the location problem. Understanding it requires something else.

The Single Responsibility Principle is usually framed as a design rule: "a class should have one reason to change." But that framing doesn't explain why classes that follow it are often easier to understand.

The SRP protects working memory by limiting the number of responsibilities within a boundary. Usually the SRP applies to the boundary of a class, but the same constraint can be applied to packages and methods.

When a boundary contains one responsibility, understanding is easier. When it mixes responsibilities, reading turns into code simulation. Simulation is time consuming and adds cognitive overhead.

The Cost of Cognitive Thrash

Our working memory is limited. We can only hold a small number of conceptual frames in our heads at once.

By "conceptual frame," I mean the mental model — the mode of reasoning — the reader uses to interpret what the code is doing. Validation logic is read differently than persistence logic. Calculation logic is read differently than logging.

A stable conceptual frame is one in which the reader can predict the type of reasoning required without repeatedly shifting mental models.

Each responsibility activates a conceptual frame. When a boundary contains multiple responsibilities, the reader must repeatedly switch frames. That context switching isn't free. The reader has to set aside one mental model, load another, and preserve the relationships between them.

That repeated switching creates cognitive thrash.

Cognitive load theory separates intrinsic load (the complexity of the problem) from extraneous load (the cost of how it's presented). The SRP doesn't reduce intrinsic complexity; pricing rules are still pricing rules. But it reduces extraneous load by limiting unnecessary frame switching inside a boundary.

Code that follows the SRP reduces context switching by stabilizing the frame contained within each boundary.

SRP Across Every Boundary

The SRP can apply to more than just the boundary created by a class definition. Any structural boundary in the system can contain (or mix) conceptual frames.

At each level, the question is the same:

Does this boundary contain one stable conceptual frame, or does it mix several?

System Level: Packages

At the package level, we can group features together. Feature-based packages increase cohesion and enable navigation. They reduce the search space and make functionality visible in the structure of the system.

When packages are organized primarily by framework layer or persistence entity, features get fragmented. Instead of navigating to a visible feature boundary, readers must search and infer relationships across layers.

At the system level, this determines whether you can find functionality without relying on memory — yours, a teammate's, or the original author's (who left three years ago).

A cohesive package structure stabilizes feature-level frames; a fragmented structure forces reconstruction and search.

Class Level: Objects

At the class level, SRP is commonly defined as:

A class should only have one reason to change.

Cognitively, that means a class should represent one coherent responsibility which activates one stable conceptual frame.

A class that validates, calculates, coordinates, persists, and logs mixes frames. Readers can't rely on the class name or structure to predict the pattern of logic inside. They must simulate execution, trace control flow, and hold multiple responsibilities in working memory.

When simulation replaces pattern recognition, reading slows down. Every interaction requires reconstruction.

Classes with a single responsibility contain one frame inside the boundary, so the reader knows what kind of logic to expect, as well as what does not belong there.

Good names reinforce that boundary. Class names with cohesive boundaries usually answer one or more of these questions:

Purpose: Why does this class exist? (InvoiceReconciliation*, OrderFulfillment*)
Role: What kind of logic is this? (*Calculator, *Validator, *Orchestrator)
Constraint: What variant is this? (*Cached*, *External*, *ReadOnly*)
Mechanism: How is it implemented? (*Jdbc*, *Stripe*, *Rest*)

The role suffix often signals the one reason the class has to change:

OrderTotalCalculator changes if calculations change.
CheckoutOrchestrator changes if sequencing changes.
RefundValidator changes if validation rules change.

These repeatable naming patterns enable pattern recognition. Pattern recognition works best when frames are stable.

Names don't create cohesion, but they do constrain what belongs inside the boundary. If a name can't meaningfully exclude logic, the class doesn't represent a single stable frame.

This is why suffixes like *Service, *Helper or *Manager tend to become junk drawers. They describe broad roles, not stable conceptual frames. Almost anything can fit inside them — and once it does, frame containment erodes.

Method Level: Units of Thought

The SRP can apply at the method level too.

For most of my career, I used helper methods to prevent duplicate code or isolate especially complicated logic.

Recently, I began using helper methods as labels for units of thought.

Instead of writing a dense public method with comments preceding each section, I now extract helper methods as labeled steps:

validateRequest();

calculateTotals();

applyDiscounts();

persistOrder();

The public method becomes a narrative. Each call marks a structural boundary around one stable conceptual frame.

Instead of holding the entire implementation in working memory, the reader processes one frame at a time.

I don't do this with every public method; just the ones that benefit from it.

A simple test:

Does the public method read like a clear sequence of steps after extraction?

If not, the extraction hasn't improved frame containment. Keep the logic inline.

When Extraction Backfires

Extraction reduces density but increases indirection.

A boundary only helps if it contains a stable frame. When extraction forces the reader to jump across multiple files or through layers of trivial delegation, it replaces conceptual compression with navigational friction.

We want to increase cohesion, not decrease it.

Warning signs:

Methods extracted that don't represent a meaningful step.
One-line delegations that merely rename trivial logic.
Control flow that requires navigating through several classes to understand a simple process.
"Micro-objects" that fragment one coherent idea across multiple files.

If extraction increases frame switching instead of reducing it, the boundary is no longer stabilizing the frame.

What Happens When Boundaries Degrade

SRP violations don't just make a single class harder to read; over time, degraded boundaries affect the entire system.

Increased Mental Simulation

When a boundary contains multiple responsibilities, skimming stops being safe. Readers can't rely on the name or the structure of the class to predict what belongs inside or what pattern of logic they'll find. They must trace execution step-by-step, juggling multiple conceptual frames in working memory.

When frames become unstable, recognition becomes unreliable and readers fall back to simulation. Recognition is fast. Simulation is slow. Over time, slow becomes normal.

Decreased Code Review Efficacy

At a small scale, one unstable boundary is an annoyance. At a large scale, unstable boundaries create systemic fatigue.

Reviewers spend more time reconstructing mental models before they can even evaluate correctness. Frame instability forces deeper inspection on every change, and eventually reviewers adapt by conserving effort. They skim when it isn't safe to skim.

Bugs hide in the noise because unstable boundaries made full understanding too expensive.

Cognitive thrash spreads beyond the original class and into the review process itself.

God Class Gravity

Classes with loosely named boundaries (OrderService, UserService) attract unrelated behavior. Because the name doesn't constrain a single responsibility, almost anything fits. The class stops representing a stable conceptual frame and becomes an expanding collection of unrelated behaviors.

Developers hesitate to introduce new cohesive classes because doing so feels like violating the team's conventions. Entropy wins.

Boundaries between functionality blur because the "entity service" contains all logic for all features that touch that entity.

Unit tests grow harder to write, read, and understand. They stop reinforcing a coherent frame and instead mirror the fragmentation of the production code.

Knowledge Concentration

When responsibility isn't visible in structure, knowledge concentrates in people instead of boundaries.

Ownership narrows to the developer who wrote the feature. Others avoid touching or refactoring that code because it feels risky. The bus factor increases.

Knowledge centralizes, and unreadable structure increases risk concentration.

Systemic Entropy

As unstable boundaries multiply, feature boundaries degrade.

Packages become dumping grounds for everything in that architectural layer. Navigability decreases as the system grows. New functionality gets fragmented to fit the existing structure.

The cost compounds, and even experienced developers struggle to onboard or safely extend the system because it's difficult to build a reliable mental model of where functionality lives.

Stable class-level boundaries reinforce package-level boundaries. When cohesion degrades at the class level, navigability degrades globally.

Systemic drag follows.

In a read-heavy discipline like software development, drag is lost performance. Readability now limits performance.

SRP Reinterpreted

SRP is often defined as:

A class should have one reason to change.

Cognitively, the rule could be defined as:

A boundary should contain one stable conceptual frame.

Software development is constrained by how quickly a team can find, understand, and safely change code. Cohesive boundaries protect comprehension at every level: package, class, and method.

The SRP reduces frame switching inside a boundary. That reduction compounds.

SRP aligns with constraints imposed by human cognition rather than being merely a stylistic preference. And individual cognition does not scale with system size.

When Write Velocity Outpaces Cognition

The number of boundaries grows as AI quickly generates code. The only way that growth remains sustainable is if those boundaries preserve frame stability instead of fragmenting it.

As code volume grows, developers spend more time reviewing and validating than writing. Effective code review relies heavily on pattern recognition. Pattern recognition depends on frame stability.

If boundaries between frames are unstable, AI amplifies the problem, and it spreads faster than ever.

When cohesion degrades, reading becomes simulation, simulation becomes cognitive thrash, thrash becomes fatigue, and fatigue becomes risk.

Applying the SRP across packages, classes and methods can help protect one resource that doesn't scale: human cognition.

Next time, I'll explore why AI makes readability more important, not less.

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 Systems for Human Brains

Mystery Meat vs. Breadcrumb Systems

Christie Cosky — Tue, 31 Mar 2026 15:00:00 +0000

It's your first week at a new job. You've checked out the repository and are scanning the package structure. The codebase is organized by *Service, *Controller, and *Repository. Within each layer, files are grouped by persistence entity: Order*, User*, Product*, and so on.

You've been asked to fix a bug in the pricing logic. Must be in OrderService, right?

You open the file. It's 4,000 lines long. Some methods are hundreds of lines.

You search for pric*. Not found.

You search the entire codebase. The word appears in seven files, scattered across variable names, constants, and magic strings. You open the first result and start reading. This doesn't seem right. You move to the next file.

You can feel the cognitive load accumulating.

Some systems make the correct starting point obvious. I'll call these breadcrumb systems.

Others require exploration. I'll call these mystery meat systems — borrowing the term from "mystery meat navigation," where the destination isn't visible until you hover over it. Unfortunately, mystery meat systems aren't unusual. They're common in codebases organized primarily around framework layers and persistence entities.

Most real systems fall somewhere in between.

Readability vs. Navigability

Designing for readability isn't just about how a file reads. It's also about how easily the system can be navigated. Navigation determines whether understanding starts immediately, or only after a search. A system can be perfectly readable and still force exploration.

Readability answers: "Can I understand this code once I'm in it?"

Navigability answers: "Can I find the right code in the first place?"

Structure determines whether capability can be found by following visible boundaries or by searching and guessing.

Exploration isn't inherently bad; it's how we learn new systems, and it's inevitable in legacy code. The problem is when exploration becomes the default mode of interaction: when every task begins with searching instead of navigating. When that happens, cognitive cost accumulates and people slow down. Navigability reduces forced exploration; it doesn't eliminate learning.

That distinction sounds subtle, but it changes the experience of working in the system. Designing code for human brains means designing how people find things, not just how they read them.

When the starting point isn't obvious, you're already using working memory before you even reach the right file. You're guessing where the logic might live, opening files and reading methods that turn out to be irrelevant. The effort adds up. Finding the code becomes part of the work.

When Structure Makes Navigation Obvious

So what does navigability look like in practice?

A system is navigable when a new developer can answer these questions without asking a teammate:

Where does this capability live?
What other parts of the system participate in it?
What ties those parts together?

If those answers are visible in structure and vocabulary, navigation doesn't depend on tribal knowledge. This means when I'm fixing a pricing bug, I should have a reasonable starting point without asking a teammate or running a full-text search.

If we want navigation instead of guesswork, capability can't live only in someone's head. It has to be visible in the structure of the codebase.

At the structural level, visibility shows up in two places:

Capability boundaries: packages or modules that reflect what the system does, not just how it runs.
Shared vocabulary: constants, enums, and other stable identifiers that tie related pieces together across classes.

When both are present, readers can navigate the codebase without guesswork.

When those signals are missing, mystery meat systems emerge.

Mystery Meat Systems

I've noticed three anti-patterns that create mystery meat systems. Every project I've worked on in my career has included at least two of the three.

Anti-Pattern 1: Organization By Framework Layer

Most modern web frameworks encourage a layered structure:

controller/
service/
repository/

This separation is useful. It clarifies technical boundaries and keeps HTTP, application logic, and persistence concerns separate.

But those layers describe how the application runs, not what the application does.

They answer questions like:

Is this handling a request?
Is this performing application logic?
Is this reading from the database?

They don't answer questions like:

What feature does this represent?
Where does the pricing logic live?

Framework layers are technical scaffolding: necessary, but not helpful in showing where a feature lives.

This isn't an argument against layering or a specific architectural philosophy. It's about navigability: whether the structure makes the right starting point obvious.

Anti-Pattern 2: Organization By Persistence Entity

In every project I've worked on, the team took layering a step further and organized within each layer by persistence entity:

UserController
UserService
UserRepository

OrderController
OrderService
OrderRepository

That worked for small CRUD systems, but as behavior grew, the business concepts got fragmented across the stack, and the codebase got harder and harder to navigate. Technical layers and persistence entities had become the navigation model, and over time, that model stopped working.

CRUD is a persistence concern, not a feature.

Grouping by entity answers the question:

Which table does this logic touch?

Grouping by feature answers a different question:

What feature does this code implement?

Most real features don't belong to a single table.

Pricing, for example, may span products, discounts, contracts, and tax rules — none of which cleanly belong to a single persistence entity. Refunds may touch orders, payments, customers, and accounting entries.

When everything is centered around a persistence entity, functionality tied to a single feature gets fragmented across controllers, services, and repositories. No single place represents the whole idea.

Centering logic on persistence entities forces exploration. You search and guess instead of navigating to a visible boundary.

In addition, classes named primarily after persistence entities and architectural roles (like OrderService or UserController) tend to accumulate unrelated behavior. Because the name encodes a persistence entity and architectural role rather than a feature, it doesn't constrain what belongs inside. The boundary stops signaling what belongs inside it.

Anti-Pattern 3: Missing Shared Vocabulary

Feature boundaries are visible in language too.

In mystery meat systems, important identifiers aren't encoded consistently. Instead, they appear as scattered hard-coded values embedded directly in conditional statements across multiple files.

When vocabulary isn't shared, related behavior becomes difficult to trace. Searching for functionality becomes a game of "guess and check." You look for one value, then another. You read the surrounding code to figure out if you're in the right place.

Without stable identifiers, you don't have a reliable way to track down specific concepts or functionality. This forces exploration instead of navigation: searching and guessing instead of following visible boundaries.

A codebase without shared vocabulary can't reliably reveal where a feature lives because the language that ties the related pieces together doesn't exist.

The alternative is to make functionality visible, both structurally and linguistically.

Breadcrumb Systems

In contrast, breadcrumb systems give you ways to navigate the system and find functionality without relying on another human. These systems enable navigation by organizing around features and shared vocabulary.

Pattern 1: Packages as Feature Boundaries

Once you organize around features instead of architectural layers or tables, packages become clear mental maps.

A package should answer:

What feature am I in?

You can still keep technical layers:

controller/
service/
repository/

But organize within them by feature.

controller/ 
  pricing/ 
    PricingController 

service/ 
  pricing/ 
    PriceCalculator 
    DiscountApplier 
    TaxCalculator 

repository/ 
  pricing/ 
    DiscountRepository 
    TaxRuleRepository 
    PriceListRepository

Now "pricing" is visible across the stack. The feature becomes the breadcrumb you follow through the layers.

If you're trying to fix a pricing bug, you don't scan every controller or every service. You go directly to:

controller.pricing
service.pricing
repository.pricing

In a breadcrumb system, you wouldn't start with OrderService. You'd start with pricing.

That's one way you get the benefits of proximity. Related behavior lives near related behavior.

Search can find text. Structure reveals relationships. The starting point becomes obvious, and that alone changes how the system feels to work in.

When packages reflect features, the system supports navigation instead of requiring exploration.

Pattern 2: Shared Vocabulary

Features aren't only visible in folders. They're also visible in language.

In breadcrumb systems, important identifiers are defined once and referenced consistently. Enums and well-scoped constants create stable identifiers for behavior.

That stability does more than improve readability. It creates structural benefits:

Traceability: related behavior can be located reliably across files.
Consistency: the same concept is referenced the same way everywhere.

When a concept has a single name and a clear home, you can navigate to its behavior instead of hunting for it.

Shared vocabulary turns language into infrastructure. It gives the system reliable reference points for its features.

When identifiers aren't stable or specific, you lose the ability to trace functionality.

Where This Goes Wrong

Like any pattern, these can be misapplied.

Structure improves navigation, but only when it reduces exploration instead of adding to it. We don't want more structure; we want clearer boundaries.

Every structural improvement carries risk.

When Packages Become Taxonomy

Packages should support navigation.

Large systems will have lots of packages. The number isn't the problem. Unclear grouping that makes navigation harder instead of easier is.

Warning signs:

Deep nesting without clear feature boundaries
Folders organized by abstract categories instead of features

Good structure narrows the search space by giving you a reliable breadcrumb. Poor structure forces you to explore. If structure increases search effort instead of narrowing it, it's working against you.

When Shared Vocabulary Fails

Introducing enums and constants isn't enough. They can be misused, too. Common failure modes include:

All identifiers are centralized in one location without regard for feature boundaries.
Constants are so abstract they don't convey any feature meaning (TRUE, ZERO).
Constants are reused across unrelated functionality.
Prefixes imply cohesion when they're actually unrelated.

In these cases, language creates another layer of indirection instead of reducing exploration. The system looks structured, but it isn't easier to navigate.

The Common Thread

Across all of these patterns, the failure is the same: instead of improving navigation, the structure increases indirection.

The goal isn't to add more folders or identifiers. The goal is to make features visible without requiring someone to trace execution across or search the entire system.

Good structure narrows the search space and supports navigation. Poor structure expands the search space and pushes readers into guesswork.

Breadcrumb Systems Can Emerge Gradually

Most systems don't start out with breadcrumbs.

On Taz, our system wasn't always organized around feature boundaries. For years, it followed the standard Java/Spring layering pattern — controllers, services, repositories — grouped by persistence entity. That's a common default, and it worked well enough early on.

But as the system grew, navigation became harder. Behavior related to a single feature was scattered across layers and files. Finding the right starting point required searching and guesswork.

About ten years in, we started introducing a new package structure organized around feature boundaries. The legacy packages remained layered by entity, but new features were built using feature boundaries. And as we refactored old code, we moved it into the new structure.

The system didn't flip overnight. For a while, it was part mystery meat, part breadcrumb.

But over time, the navigable surface area grew. Exploration shrank. The default starting point became clearer. Instead of accumulating entropy, the system gradually became easier to understand.

You don't need perfect architecture to improve navigability. Even inside a legacy system, you can begin introducing visible feature boundaries and shared vocabulary. Each new boundary reduces search space for the next person who has to read the code.

Navigability compounds over time. Small structural improvements, repeated consistently, shift how the entire system feels to work in.

Even if you're currently in a mystery meat system, you can start leaving breadcrumbs now.

What About Microservices?

The same principle applies even when the system is distributed.

In distributed systems, cross-service navigation is inherently harder. Some exploration is unavoidable. But inside each boundary, navigability is still possible.

You may not control the entire ecosystem. You may not be able to reorganize every microservice. But you can make the ones you touch internally navigable, with visible feature boundaries and shared vocabulary.

Global coherence may be too lofty a goal, but local coherence will help shrink the search space for the next reader.

Navigation Is The First Step

Organizing around feature boundaries makes it possible to find the right part of the system. But finding the right file doesn't mean the file itself is readable.

Once you're inside a package, the question changes:

Does this class make its purpose visible?
Or do you still have to simulate execution to understand it?

Structure determines whether you can find the code. Cohesion determines whether you can understand it. Navigability gets you to the right room; cohesion determines whether the room makes sense once you're inside it.

When finding the right code takes longer, every review, bug fix, and feature change slows down because the starting point is unclear.

If software performance depends on how quickly a team can understand and safely change a system, then navigability becomes part of its performance. The faster the right starting point can be located, the less cognitive overhead a change requires.

Navigation is step one. Cohesion is step two.

That leads directly to the Single Responsibility Principle as a design tool for reducing mental load, which will be my next post.

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 Systems for Human Brains

Readability Is a Performance Constraint

Christie Cosky — Mon, 02 Mar 2026 00:43:37 +0000

Most teams obsess over execution speed: build speed, runtime performance, delivery velocity.

But there's another bottleneck we rarely measure: how long it takes a human to understand the code.

Open a file during a production incident. The clock is ticking. You're scanning for the bug. If the structure is unclear, you waste time just figuring out what you're looking at.

Readability is more than style. It's a performance constraint.

Software development is a read-heavy discipline. Code is written once and read repeatedly — during code reviews, debugging sessions, refactors, feature enhancements, and production incidents, often under time pressure. When code is hard to read, understanding slows down. When understanding slows down, velocity drops and risk increases.

To be clear, there are contexts where optimizing for speed is rational. But when the code is expected to change and grow over time, readability isn't optional overhead.

Performance Depends on Reading, Not Writing

We write code once, but we read it for years.

The majority of software development effort isn't typing new logic; it's reconstructing mental models while reading what already exists. If most engineering time is spent reading and modifying existing code, that's the hot path. Even small reductions in comprehension time compound across reviews, fixes, and feature changes.

The bottleneck isn't typing speed; it's the speed of reading and understanding. In a read-heavy system, that makes readability a performance constraint, not a stylistic preference.

The First Bottleneck Is Perception

We don't read code line-by-line like a compiler. Structure is processed before logic.

When structure is unclear, working memory fills with extraneous cognitive load, leaving less capacity to reason about the code itself. It's like running too many programs at once: performance drops.

Unreadable code slows understanding by consuming the cognitive resources required to make correct decisions.

Optimizing for Writes Slows the System

In cultures that prize speed above all else, teams often optimize for writes. Code optimized for writes often lacks clarity, and much of the context lives only in the author's head. In these environments, short-term urgency consistently outruns long-term maintainability.

The cost of re-reading gets pushed downstream — to reviewers, on-call teammates, and future maintainers. They pay the cognitive tax. Over time, that compounds.

Code optimized for reads may take longer to write, but it shortens time-to-understanding, reduces review friction, and lowers change risk.

This isn't polishing; it's throughput protection.

Readability is an up-front investment that shifts cost left. It increases writing time slightly in exchange for reducing every future interaction cost — review time, debugging time, onboarding time, and refactoring time. In systems that are read repeatedly, that trade pays for itself.

Unreadable Code Concentrates Knowledge — and Risk

Most teams have at least one feature that "belongs" to a single developer. It's usually difficult to understand and completely avoided by the rest of the team. We joke that writing code nobody else understands is "job security." It stops being funny when that person leaves.

Unreadable code concentrates knowledge. When understanding is expensive, fewer people are willing to pay the cost. Ownership narrows, incidents escalate to the one person who "knows how it works," and refactors are avoided because the risk feels too high.

That's not an aesthetics problem. That's a risk concentration problem.

Over time, this increases the "bus factor": the number of people who would need to be hit by a bus before the system becomes unmaintainable.

Readable code lowers the energy required to understand and modify a feature. Knowledge spreads. Ownership widens. Operational risk decreases.

Readability creates redundancy in human understanding — and redundancy is how systems stay resilient.

Structure Exposes Errors

When logic follows consistent patterns (using perceptual principles like repetition, hierarchy, and alignment), inconsistencies become visible. When I can see the patterns in my code, problems sometimes jump out: "Duh, how did I miss that?" Well-structured code allows the pattern-matching brain to notice what doesn't match.

In code reviews, predictable structure lets reviewers safely scan for inconsistencies instead of reconstructing the entire mental model from scratch. When structure is unclear, bugs hide in the noise and are discovered in QA or production later — when the context has faded and the cost of fixing them is higher.

Readable code prevents mistakes and makes them visible while they're still cheap to fix.

Experience Shifts the Optimization Target

Over time, many developers learn the same lesson: unreadable code is expensive.

They inherit parts of the codebase that technically "work" but are impossible to understand. They review changes that take longer to understand than they did to write. They refactor code whose original intent is unclear.

Experience changes the optimization target.

Early in my career, I optimized for speed. I was praised for finishing tasks quickly, so that's what I focused on. When I look back at some of my early personal projects, I see god classes, massive methods, and long unbroken walls of code. It worked — but it was optimized for writes, not reads.

Over time, my priorities changed from local velocity ("How fast can I finish?") to system velocity ("How easy can I make this to understand and change in the future?").

Many experienced developers make that shift — not because they became perfectionists, but because they've paid the cost of unreadable code.

Some developers argue that working code can be cleaned up later. In practice, this rarely happens. Cleanup competes with new deadlines, and new deadlines almost always take precedence. (As I like to say, entropy always wins!)

Readability Is a Team Multiplier

Code Reviews

Readable code lowers the cost of understanding during review. When the structure and intent are clear, reviewers can focus on correctness instead of reconstructing the mental model from scratch. Reviews become faster and more effective.

Unreadable code does the opposite. Large, dense changes increase review fatigue and time-to-understanding. When understanding is expensive, reviewers conserve their energy. They skim when it isn't safe to do so and approve changes they don't fully understand.

Readable code increases the probability that reviews actually catch the right problems.

Coordination Cost

When intent is visible in the code, fewer meetings are required to explain it. Developers don't need to ask for walkthroughs of control flow just to make a small change.

When it's not, meetings and messages are required to answer questions — often multiple times to multiple developers over time. The knowledge lives in chat messages and in the original author's head.

Readability reduces repeat explanations.

Load Distribution

In unreadable codebases, certain developers become the "translators" of the logic. They are pulled into meetings, pinged constantly, and have their time consumed by answering questions and validating changes. They become bottlenecks.

Readable systems distribute cognitive load. Changes aren't dependent on a single person's availability. That's not just a bus factor issue; it's structural load-balancing.

Onboarding Velocity

In a readable system, a new developer can build a mental model by skimming structure and names. In an unreadable one, onboarding requires synchronous explanations and tribal knowledge. Understanding doesn't scale.

Psychological Safety

When developers struggle to understand code, they often blame themselves. They question their competence, hesitate to ask questions, and avoid touching risky areas as much as they can. That erodes morale and confidence and can eventually affect retention. I have experienced this myself.

Readable systems reinforce competence. Developers can understand, complete their work independently, and contribute without fear. And developers who aren't afraid to touch the code move faster, ask better questions, and take ownership more readily — which feeds directly back into throughput.

Scale Requires Consistency

As systems grow, inconsistency becomes more expensive.

In a small codebase with a small team, structural differences are tolerable. Context lives in shared memory and conversation. But as the codebase grows, the team grows, and time passes, that tolerance disappears.

Large codebases rely on shared patterns, not shared memory.

When similar problems are solved in similar ways, developers learn how to read the system. Patterns become familiar, and structure becomes predictable. They know where to look and what shape new code should take. When they add their own changes, they reinforce those patterns instead of inventing new ones.

Inconsistent systems are unfamiliar and unpredictable. Each file must be reinterpreted from scratch. Every change requires learning a new pattern. Developers hesitate to make changes or require validation from others that their changes are correct. Understanding doesn't accumulate; it resets. That re-learning cost grows with the size of the system.

You can't scale shared understanding without structural consistency.

Without it, every change requires deep context reconstruction. With it, understanding becomes incremental, and incremental understanding is what makes large systems sustainable.

Understanding Is the Performance Constraint

Velocity is often measured in outputs: tickets closed, commits merged, lines of code written. Those metrics optimize for writes — short-term wins and visible activity.

Comprehension speed is invisible.

If we could measure read-optimized velocity, we'd track how quickly a human can understand and safely change the code.

Code volume is increasing rapidly. I recently generated 11,000 lines of code (including comments and tests) in three days using AI tooling. It took me more than twice as long to review, restructure, and refactor it into something I actually understood.

Writing has never been the primary constraint. Understanding has.

AI removes friction from writing, but the underlying performance constraint hasn't changed. If organizations don't rebalance toward comprehension, the gap between write speed and understanding speed widens — and velocity eventually slows under its own weight.

Experienced teams stay fast because of readable code, not in spite of taking the time to write it that way.

If performance is constrained by understanding, then structure isn't cosmetic. It's throughput protection.

AI is accelerating write velocity. But review, comprehension, and safe change still depend on human cognition — and cognition doesn't scale with code volume.

That makes readability more important now than it was five years ago, not less.

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 Systems for Human Brains