DEV Community: Christie Cosky

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.

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

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.

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

I'm curious how other teams approach this:

Do you optimize more for write speed or read speed?
Have you seen unreadable code become a systemic bottleneck?
Has AI changed how you think about maintainability?