Forem: Christie Cosky

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