Misalignment: When We Don’t Share the Same Mental Model

Misalignment happens when people involved in a project hold different understandings of what problem they’re solving, what success looks like, or how to get there. It’s one of the most subtle yet pervasive sources of accidental complexity — and it often goes unnoticed until the cost shows up in code.

What starts as a simple feature request can become an entangled mess when stakeholders, designers, and developers all interpret the task differently. Without a shared mental model, we build systems that reflect our assumptions — not the actual problem.

Vision Misalignment

One of the most fundamental forms of misalignment is simply not agreeing on what we’re building or why. Different stakeholders — product managers, designers, developers, leadership — may have conflicting interpretations of the goals, user needs, or constraints.

• Sometimes, there’s no clearly defined problem at all — just an assumption that something “should” be done.
• In other cases, long-term strategic goals clash with short-term business needs.
• “Business rules” might be defined in multiple places — and none of them match.
• Product decisions are driven by opinions or hunches rather than data, leading to design churn and unclear priorities.

Misaligned Priorities

Even when the vision is clear, different roles often optimize for different outcomes:

• Developers want clean code and test coverage, assuming they’re building production-ready systems.
• Product managers focus on MVP speed and user validation — assuming the work is disposable.
• One team might be optimizing for performance, another for flexibility, a third for time-to-market.

These differences aren’t inherently bad — they reflect healthy tension. But without explicit alignment, they lead to subtle mismatches in expectations, scope creep, and rushed compromises.

Example: A developer spends extra time implementing a flexible architecture for future extensibility. The PM, assuming this is a throwaway prototype, is frustrated by the delay — and the result pleases no one.

Ambiguity and Vague Requirements

A more granular form of misalignment appears in vague or ambiguous requirements. This often stems from incomplete transfer of context between those who define problems (PMs, designers) and those who implement solutions (developers).

• Assumptions go unstated.
• Domain details are missing or under-explained.
• Critical constraints are implied, not documented.
• Non-functional requirements are forgotten (security, performance, accessibility)

When this happens, developers are left to interpret the feature based on their own mental models. The result may function — but not match the intent.

Example: A ticket says “add a price filter.” The developer adds a min–max input field. Later it turns out the business needed predefined price brackets (e.g., “Under $100”), and the implementation doesn’t fit the UI or backend model.

Organizational Silos

Organizational silos are another form of misalignment — but instead of differing opinions, they stem from a lack of shared visibility. Different teams or roles work toward a common goal but do so in parallel, without enough coordination or understanding of each other’s work. Everyone might be technically aligned on what to build, yet disconnected on how, why, or under which constraints. The result is a fractured system that’s more complex than it needs to be — not because the problem is hard, but because the communication is sparse.

You’ll see this when frontend and backend teams design an API without agreeing on data structures. When product and engineering align on features but not on edge cases. When designers hand off polished mockups that assume capabilities the platform doesn’t support. Or when QA and devs test and release features on different timelines. Each of these scenarios leads to misfit parts that need glue code, translation layers, or workarounds — all of which increase complexity without adding business value.

Silos often emerge naturally as teams specialize or grow. But the core issue is always the same: lack of shared understanding in real time. When teams don’t talk early and often, they make assumptions. And when those assumptions diverge, complexity fills the gap — not with better solutions, but with fragile connectors that patch over the misalignment.

Consequences of Misalignment

Misalignment doesn’t just lead to frustration or delays — it directly adds accidental complexity to the system. Here’s how:

• Redundant logic: Different teams or individuals implement the same rules in slightly different ways — leading to duplication, drift, and inconsistency across modules.
• Glue code and workarounds: Misunderstandings between teams (e.g. between frontend and backend, or between services) often result in a tangle of adapters, transformers, and “glue” logic that doesn’t solve a business problem — it just reconciles mismatched assumptions.
• Overgeneralized solutions: When trying to cover everyone’s interpretation of a problem, we often end up building something overly flexible — with extra flags, parameters, conditionals, or configuration options that few fully understand or use.
• Rewrites and rework: Code built under the wrong assumptions often needs to be torn down and redone, introducing churn and technical debt that could’ve been avoided with clearer alignment from the start.
• Hidden complexity: The reasons behind certain decisions become hard to trace, especially when they originate from conflicting or unclear expectations. Future developers are left guessing why something was built the way it was — and often afraid to touch it.

❗ Misalignment doesn’t always show up as a visible bug. It shows up as extra logic, fragile workarounds, mismatched interfaces, and an uneasy feeling that “this is more complicated than it needs to be.”

The bottom line: every misunderstanding upstream multiplies complexity downstream. The longer it goes unaddressed, the more code it takes to compensate for it.

Inconsistency: The Hidden Complexity Multiplier

Inconsistency across a project or organization might seem like a minor issue — a formatting style here, a naming variation there — but over time, it becomes a silent multiplier of complexity. It introduces friction in understanding, navigating, and contributing to code, particularly in growing teams or large codebases. Even when the code is technically correct, inconsistency forces developers to re-learn patterns, second-guess intentions, or stop to decipher why something was done differently.

You’ll see it in mismatched naming conventions, structural patterns that vary between modules, or different implementations of the same logic across features. One part of the app uses async/await, another uses callbacks. Some modules use MVVM, others don’t follow any pattern. Even small differences — like how date formatting is handled or where configuration lives — can add up.

Why is inconsistency so expensive? Because humans rely heavily on pattern recognition to reduce cognitive load. When patterns are familiar and predictable, we move faster and with more confidence. But inconsistency breaks that flow and introduces extra cognitive effort.

Here’s how inconsistency increases complexity:

• Increased mental overhead: Developers must constantly switch mental models when moving between modules or teams that barely resemble one another.
• More room for error: Inconsistent naming or structure makes it easier to misunderstand what a piece of code does — or miss important edge cases.
• Harder navigation: Without shared structure or naming, finding where something lives in the codebase takes longer.
• Redundant discussions and PR churn: Inconsistent style leads to debates in code reviews that could be solved by shared rules.
• Slower onboarding: Newcomers have more to learn, more context to absorb, and more habits to unlearn when every part of the system looks and behaves differently.
• Decision fatigue: Developers spend time making decisions about formatting, naming, or architecture that could be solved once through agreement or codestyle guides.

Consistency is more than just aesthetic — it’s a design decision that makes software easier to understand, evolve, and scale. Establishing shared conventions, architectural patterns, naming rules, and tooling (like linters, templates, and CI pipelines) helps protect against unnecessary complexity. The goal isn’t rigid standardization, but clarity: when developers move across the codebase, they shouldn’t feel like they’ve entered a different world. Familiarity lowers mental load — and that’s one of the simplest ways to keep complexity in check.

Organizational Design Shapes System Design

One of the most profound — yet often overlooked — sources of complexity is how our teams are structured. As Conway’s Law famously states:

“Any organization that designs a system will produce a design whose structure is a copy of the organization’s communication structure.”

In other words, your architecture mirrors your org chart. When teams are siloed, their systems become siloed. When teams struggle to collaborate, their code reflects that friction. And when teams are optimized for autonomy, their modules become independent — sometimes overly so.

This isn’t always bad. Conway’s Law isn’t a warning — it’s a description of reality. Aligning architecture with team boundaries can actually reduce coordination overhead. But the downside is clear: organizational complexity breeds system complexity. For example:

• A feature that spans multiple teams may require coordination between frontend, backend, infrastructure, and design — each with their own roadmaps and priorities.
• To respect team boundaries, logic might be split across services or modules that aren’t naturally separate — introducing glue code, abstractions, and coordination mechanisms.
• Autonomy can lead to redundancy — different teams solving similar problems in different ways, with different tools or assumptions.

What begins as a strategy to scale teams can lead to fragmented systems with duplicated logic, excessive generalization, and complex workflows that serve the organization’s shape more than the user’s needs.

Understanding this relationship helps us make better decisions. If we know the system will reflect the structure of our teams, we can shape those structures with intention. Cross-functional teams, clear shared ownership, and regular syncs between collaborators reduce the architectural scars of organizational misalignment.

And when reorganization isn’t feasible, awareness itself becomes a tool. If we know that our team boundaries introduce complexity, we can invest in simplifying the seams: shared contracts, well-defined APIs, good documentation, and thoughtful glue code. Because sometimes, the best way to fix the architecture… is to fix how we work together.

The Alignment–Chaos Spectrum

When it comes to organizational and system design, we are always balancing between two forces: alignment and chaos.

• Too little alignment, and we descend into chaos — duplicated solutions, incompatible modules, inconsistent APIs, and endless miscommunication.
• Too much alignment, and we fall into rigidity — stifling flexibility, creating one-size-fits-all solutions, and forcing awkward fits for problems that don’t belong in the same mold.

Neither extreme is healthy. Complexity grows both when teams are too independent and when they are too tightly bound.

In a startup, a bit of chaos is survivable — even necessary. Agility matters more than perfect structure. In a large corporation, alignment is critical to avoid duplicated effort and to maintain coherence across massive systems. But even there, too much standardization can become its own kind of complexity: developers spend more time conforming to rules than solving real problems.

Finding the right point on the alignment–chaos spectrum is not about enforcing rigid standards or letting everything evolve organically. It’s about choosing where consistency matters most — and where flexibility should be preserved.

Some helpful questions to guide these choices:

• Which areas are critical for our product (UI, security, fast feature delivery, API design, rich documentation)?
• Where does inconsistency create real cognitive load for developers or users?
• Where does forced consistency create unnecessary complexity or cost?
• Which areas can tolerate divergence (internal module structure, small utility patterns)?

Alignment should focus on principles and shared understanding, not on micromanaging every decision. For example:

• Agreeing that all APIs should be versioned, even if different services use slightly different tooling.
• Agreeing that features should be modular and testable, without forcing the same exact folder structure everywhere.
• Agreen that all the features of the mobile app use common modules/libraries/approaches for networking, encryption, analytics, UI animation, and so on.

When we treat alignment and autonomy not as absolutes but as a spectrum to be tuned based on context, we gain a powerful tool to manage complexity consciously — rather than reactively.

The Challenge of Scaling Alignment

When an organization grows, two natural forces come into play:

• Autonomy needs to increase to keep teams agile and motivated. Each team needs the space to make local decisions without endless cross-team negotiation.
• Alignment becomes harder because there are more moving parts, more diverse needs, and longer communication paths.

Finding the right balance between alignment and flexibility isn’t a one-time decision. As organizations scale, what once made sense at 5 people might break down at 50, and what worked at 50 might crumble at 500. New teams form, responsibilities shift, and technical debt compounds. Alignment must be treated as an evolving, living system — something we revisit regularly to keep complexity manageable without stifling autonomy.

Familiarity Is Not Simplicity

When you’ve been in the same organization or working on the same project for a long time, you naturally adapt to its quirks — even the overly complex ones. But just because something feels familiar doesn’t mean it’s simple. Familiarity masks complexity. You stop noticing the awkward workflows, overloaded abstractions, or brittle architecture — not because they’ve become better, but because you’ve built mental shortcuts around them.

That’s why it’s important to listen to newcomers. Fresh eyes often spot convoluted patterns or redundant processes that long-timers no longer question. If they point out areas of confusion or unnecessary indirection, take it seriously — it might be time to clean things up.

A related trap is unclear responsibility. When ownership boundaries aren’t well defined, work gets messy — not just in the code, but across the whole development process. And messy systems, organizational or technical, are always harder to navigate, reason about, and maintain.

Strategies for Evolving Alignment

• Principle-Based Governance
  Instead of hard rules for every decision, define a few strong principles that guide teams in making their own aligned choices (e.g., “Favor explicit over implicit dependencies” or “Prioritize local reasoning in APIs”).

• Lightweight Alignment Forums
  Create spaces (like architecture circles, guilds, or working groups) where interested developers discuss and update shared practices — without heavy-handed command-and-control.

• Versioning and Layered Contracts
  Allow systems to evolve by versioning APIs, internal modules and services, and shared libraries. Not everything has to align instantly — progressive adoption is key.

• Clear Boundaries and Ownership
  Explicitly define system ownership. When boundaries are clear, teams can innovate internally while maintaining stable interfaces externally.

• Celebrating Simplicity
  Recognize and reward teams that remove complexity, not just those who add impressive-looking abstractions. Make simplicity part of your technical culture.

Ultimately, alignment isn’t about creating the One True Way. It’s about minimizing the unnecessary complexity that grows when communication, expectations, and responsibilities drift apart — while leaving space for the necessary complexity that arises from solving real-world problems.

Conclusion

Misalignment, inconsistency, and siloed collaboration don’t just slow us down — they silently shape our systems, making them harder to understand, evolve, and maintain. Complexity doesn’t come only from within the code — it emerges from the spaces between people: from miscommunication, vague expectations, inconsistent decisions, and disconnected teams. These invisible dynamics leave very real traces in every layer of our systems.

If we want to reduce complexity, we can’t focus solely on technical design. We have to shape the environment in which software is designed. That means building strong feedback loops, aligning on principles over rigid processes, and fostering a culture of collaboration and mutual understanding. It means recognizing that organizational structure, communication practices, and cultural defaults all influence the clarity — or confusion — of what we build.

Every organization must find its own balance between alignment and chaos. Too little alignment, and inconsistency and redundancy take over. Too much, and flexibility disappears. But if we invest in clear boundaries, shared principles, and continuous conversation, alignment becomes not a constraint, but a force multiplier. The real challenge isn’t just writing better code — it’s creating the conditions where better code can be written.

Cognitive Limits

The entire topic of complexity in software ultimately stems from a fundamental truth: our cognitive capacity is limited.

Our working memory can only hold a small number of items at once — a constraint famously known as the 7±2 rule. (We’ve shared more on that in the introduction to this topic)

Because of this, we’re forced to organize code in ways that reduce the number of things we have to think about at the same time. That’s why we spend so much time discussing how to design our modules, structure abstractions, and align the level of detail with the context in which the code is used. (We’ve explored these topics in earlier chapters: part 1, part 2, part 3, part 4, part 5, check them out for a deeper dive.)

But memory limitations are only one part of the story. There are several other traits of human cognition that shape how we write and experience code:

Difficulty with State Tracking

Humans are notoriously bad at holding multiple possible states in mind — especially when those states are implicit. When reading code, we often have to mentally simulate different paths: “What happens if this flag is true?”, “Is this variable already set?”, “Which branch are we in right now?” As the number of possible states grows, our ability to reason about the system drops sharply. This is why deeply stateful systems, boolean flags, and side-effect-heavy logic can become so cognitively expensive — even when they’re technically correct.

Poor Handling of Indirection

Indirection is a powerful tool — we use it to make code modular, abstract, and reusable. But every level of indirection makes it harder to trace what’s actually happening. When a function calls a method on a dependency, which is a protocol-backed abstraction that calls another injected service, we’ve added multiple hops for the brain to follow. Protocols, callbacks, dependency injection, and decorators are all useful — but they come at a cost. Too much indirection breaks our intuitive grasp of control flow and turns even simple tasks into a scavenger hunt.

Context Switching Is Expensive

Whenever we switch from one file, type, or layer to another, we need to load a new mental model. That mental juggling slows us down and increases the chance of mistakes. If your current task requires bouncing between the view, the model, two unrelated services, and a shared utility, the mental overhead becomes significant. This is why we care so much about cohesion and coupling. When related logic is kept close together, and unrelated logic is clearly separated, we can stay focused on a task without constantly reorienting ourselves.

Preference for Linear Thinking

We’re much better at understanding sequences than branches. Code that reads like a clear, step-by-step story is far easier to follow than logic that fans out into deeply nested conditionals or recursive calls. When possible, flat, linear flows reduce mental strain. This doesn’t mean avoiding branching entirely, but it does mean we should be mindful of how deep and how scattered that branching becomes — especially when the logic is spread across multiple files or functions.

Cognitive Fatigue

Even the clearest code becomes hard to work with when we’re tired, stressed, or under pressure — which is often the case in real development. What seems like a minor complexity in the morning can feel like a blocker at 6 PM after a day of meetings and bug triaging. This is why we should aim to write code that’s easy to understand not just in theory, but in practice — under less-than-ideal conditions. Clear, localized, well-named logic helps future you (or your teammates) work more effectively when mental energy is low.

Cognitive Biases

All human beings are biased. We don’t perceive the world exactly as it is — we filter it through years of experience, instinct, and evolved mental shortcuts. These shortcuts, known as cognitive biases, help us make decisions quickly and efficiently, especially under uncertainty. They evolved to help our ancestors survive — to avoid danger, spot opportunities, and act fast when time mattered most.

In many real-world situations, these instincts are helpful. They allow us to judge quickly, act decisively, and reduce decision fatigue. But in software development — where the problems are abstract, the consequences delayed, and the systems complex — these same instincts can easily mislead us.

Books like Thinking, Fast and Slow by Daniel Kahneman and Predictably Irrational by Dan Ariely explore the nature of these biases in depth, revealing just how irrational even our most “logical” thinking can be. Let’s look at a few common cognitive biases and how they influence the decisions we make in our work — often adding accidental complexity to our systems.

Complexity Bias

We tend to assume that complex problems require complex solutions. Simple answers feel naive, incomplete, or unworthy of real-world use — even when they’re exactly what’s needed.

For example, we might skip using a basic dictionary or an enum to model a small state machine and instead introduce a full-blown state pattern with protocols, coordinators, and factories — not because the problem demands it, but because it feels like a better-engineered solution. The result? More indirection, more surface area, and more mental effort to maintain something that could have been straightforward.

Simplicity Bias

At the other extreme, we sometimes believe that one simple idea can solve all our problems. This is the “silver bullet” mindset — believing that a new framework, language, or architecture will fix everything.

We see this when teams latch onto new technologies and try to apply them everywhere. But reality rarely conforms to a single tool. For instance, switching to a reactive programming framework might simplify some flows but introduce unnecessary complexity in others. Overcommitting to a universal solution often leads to misfit abstractions and workarounds that break the simplicity we were after.

Foreseeing the Future

Our ability to imagine the future helped humans survive. But in software, our predictions are often wrong.

We design for imagined scale, performance, and reusability — and build systems that are far more complex than they need to be. We add abstraction layers, generalize interfaces, or design elaborate plugin architectures for a feature that might never grow. The future-proof solution feels responsible in the moment — but if that future never arrives, we’re left maintaining complexity that no longer serves a purpose.

The same happens with premature optimization. We spend days crafting modular architecture, separating every concern, or making our scroll views buttery smooth — in an MVP no one has used yet. We optimize for problems we might face, rather than focusing on what matters now.

Conformism and Cargo Cults

Humans are social creatures. We learn by imitation — especially from those we perceive as successful. But copying without understanding is risky.

In software, this manifests as cargo culting — adopting tools or practices simply because others (often big companies) do. One famous example: Airbnb adopted React Native for their mobile app, later found it misaligned with their needs, and moved away from it. Yet many teams continue to use React Native because Airbnb once did, not considering whether it’s right for their own scale and context.

Anchoring Bias

Once we make an initial choice, we tend to stick with it — even when the context changes.

Let’s say a team has used UIKit for a decade. Even as SwiftUI matures and becomes a better fit for new features, they continue to build everything the old way — not because it’s better, but because it’s familiar. The initial decision becomes an unspoken prerequisite. We stop evaluating it critically and treat it as a fixed point in our reasoning.

Confirmation Bias

We naturally seek information that supports what we already believe and ignore what contradicts it.

If we think a particular architecture is superior, we’ll highlight examples where it worked and dismiss the ones where it didn’t. This bias slows down learning and locks us into suboptimal patterns. It makes us blind to flaws in our own code and resistant to alternative perspectives — both of which are essential to reducing complexity.

Sunk Cost Fallacy

This bias leads us to continue investing in something because we’ve already put time, effort, or resources into it — even when it no longer makes sense.

For example, a team might recognize that Core Data is no longer meeting their needs. But because they’ve already built everything around it, switching feels like admitting failure or “wasting” past work. So they keep investing in the old system, layering on patches and workarounds, increasing complexity with every iteration — instead of making a clean break.

Pattern Recognition (and Misapplication)

Our brains are wired to spot patterns — it’s how we learn. But sometimes we see patterns where none exist, or we apply old solutions to new problems that only look similar.

For instance, seeing that two features share a similar flow, we abstract their logic into a shared module. But small differences begin to emerge — and soon the abstraction becomes a tangle of conditionals trying to accommodate both. What started as an effort to simplify ends up more complex than the originals.

Biases shape our subjective reality, influencing our decision-making and problem-solving processes. Ultimately, they can lead us to incorrect understanding of the situation, wrong conclusions resulting in solutions that fail to fully address the problem and instead introduce unnecessary complexity.

Developers’ Specifics: When Complexity Becomes a Temptation

Beyond the general cognitive biases we all share, software developers have their own unique tendencies — shaped by the nature of the work, the culture of the industry, and the psychology of technical problem-solving. These tendencies don’t just tolerate complexity — they sometimes invite it.

Simple Solutions Are Boring

Many developers, especially experienced ones, find little excitement in straightforward answers. A problem that can be solved in ten lines of code might not feel “interesting” enough. Instead, we look for elegant patterns, clever abstractions, or novel techniques — not because they’re needed, but because they’re fun. This often results in solutions that are harder to read, test, or maintain — even though they were more enjoyable to build.

The God Syndrome

There’s a subtle, almost mythic appeal to mastering complexity. Building something deeply abstract or highly optimized — something only you or a few others truly understand — can feel like a power move. The more sophisticated our code becomes, the more control and intellectual dominance we might feel. But this illusion of mastery can be dangerous: systems built for intellectual satisfaction often become fragile, opaque, and intimidating for others.

Social Reinforcement of Complexity

Complexity is frequently rewarded in various professional domains from academia to industry, and software development is also among them. In code reviews, presentations, or open-source projects, intricate solutions are often met with admiration — even when a simpler alternative would be more maintainable. In tech culture, solving something in a clever way is often valued more than solving it in a clear way. This dynamic reinforces habits that prioritize impressiveness over simplicity.

Reinventing the Wheel

For many developers (myself included), solving problems from scratch is one of the most enjoyable parts of the job. Even when well-tested libraries, frameworks, or even components from our own projects already exist to solve the problem, we sometimes choose to build a new solution. We justify it as being more “tailored to our needs,” but it often duplicates effort and introduces new maintenance burdens. Reinvention gives us a sense of ownership and technical fulfillment — but it can also add unnecessary complexity to systems that didn’t require it.

CV-Driven Development

Sometimes, complexity isn’t introduced for technical reasons at all — but for career visibility. Adopting trendy architectures, experimental tools, or heavyweight frameworks can be justified as “future-proofing” or “scaling,” when in reality they’re resume boosters. We rationalize that these technologies will “look good on GitHub” or during interviews — even if they overcomplicate the current product.

Personal Traits and Complexity

Beyond the biases, there’s another important factor influencing the complexity of our solutions — our individual personalities.

We all bring a unique mix of temperament, preferences, strengths, and fears to our work. These personal traits shape how we interpret problems, what kind of solutions we gravitate toward, and how we approach uncertainty. The result? Even with the same technical skills and constraints, two developers may solve the same problem in entirely different ways — with wildly different complexity profiles.

Here are some of the personality-driven behaviors that subtly (or not-so-subtly) influence the decisions we make.

Risk Tolerance and Change Aversion

Some developers thrive on experimentation, eager to adopt new tools, rewrite old modules, or rethink established structures. Others prefer stability — valuing predictability, reliability, and minimizing disruption.

• High risk-tolerance can lead to innovation and architectural progress — but also to instability and churn.
• Low risk-tolerance protects against breaking changes, but can entrench legacy systems and block necessary evolution.

🧩 Example: One developer pushes to migrate a legacy feature to Swift Concurrency. Another resists, citing edge cases and team ramp-up time. The resulting compromise is a hybrid system that’s more complex than either approach on its own.

Perfectionism vs. Pragmatism

Perfectionists strive for clean abstractions, polished code, and comprehensive solutions — sometimes to the point of over-engineering. Pragmatists, on the other hand, optimize for getting things done with minimal friction.

• Perfectionism can lead to elegant but bloated designs.
• Pragmatism can lead to faster delivery but more technical debt — especially when context is ignored.

🧩 Example: A team creates a generic plugin-based form engine that can handle any field type. The product only needs two. The overhead ends up outweighing the benefit.

Detail-Oriented vs. Big Picture Thinkers

Some developers obsess over implementation detail — performance, edge cases, data layout. Others focus on architecture, workflows, and long-term design.

• Detail-oriented devs may introduce low-level complexity in the name of precision.
• Big-picture thinkers may miss technical pitfalls while chasing architectural ideals.

🧩 Example: One dev optimizes data caching with custom flags and serialization. Another finds it too hard to use and starts building a parallel system — doubling the complexity.

Control-Oriented vs. Delegators

Control-oriented developers prefer to own the entire stack, building their own solutions for predictability. Delegators trust libraries, services, and abstraction to do the heavy lifting.

• Too much control leads to reinvention and high maintenance.
• Too much delegation can result in black-box dependencies and unexpected edge cases.

🧩 Example: A team builds a custom HTTP client for “full control.” Later, they struggle to add standard features like retries and authentication that a third-party library already offered out of the box.

Confidence and Experience Level

Confidence shapes how developers make trade-offs. Less experienced developers may over-rely on frameworks or patterns they’ve seen in tutorials. More experienced ones may overgeneralize from past projects — even when the context has changed.

🧩 Example: A junior developer uses a BaseViewModel pattern because it’s common in examples — even though the app doesn’t need it. A senior developer insists on custom DI infrastructure because “that’s what worked in the past,” ignoring better options.

Communication Style and Assertiveness

In team environments, not all decisions are made by the most thoughtful person — sometimes they’re made by the most vocal one. Developers who are confident and articulate may steer teams toward or away from certain solutions. Those who are quieter may struggle to challenge decisions — even when they spot emerging complexity.

🧩 Example: A persuasive developer pushes Clean Architecture for a simple app. The team complies, but ends up with fragmented modules and ceremony-heavy code that no one enjoys working with.

Navigating Complexity with Self-Awareness

At its core, software complexity isn’t just a technical challenge — it’s a human one. Our cognitive limits, personal traits, biases, and emotional instincts are deeply woven into the systems we build. We like to imagine ourselves as rational, logic-driven engineers, but the truth is more nuanced. Every decision — from architecture to variable naming — is filtered through the lens of how we think, feel, percieve the world and relate to others.

Acknowledging Human Nature

The first step toward managing this complexity is simple: awareness. You can’t remove cognitive biases or overcome your working memory limits — but you can notice them. By naming our instincts, we give ourselves a moment to pause, reflect, and respond with intention instead of habit. Recognizing that our brains are optimized for survival, not systems design, helps us work with our limitations rather than against them.

Recognize the Invisible Forces

Before reaching for a solution, step back. Ask yourself: Why am I really making this choice?
Is this abstraction for clarity — or for cleverness?
Am I resisting a change because it’s risky — or because it’s genuinely unnecessary?
Am I repeating a familiar pattern just because it’s comfortable?

And then look beyond yourself:
Is the technical direction being shaped by thoughtful discussion — or by the loudest voice in the room?
Are diverse perspectives being heard, especially from those who may be quieter or newer to the team?

Build Systems That Guide Behavior

Not all complexity comes from individual behavior. Sometimes it’s baked into the culture, the process, or the tooling. That’s why we need to intentionally shape our environment to support good decisions:

• Favor conventions and templates that encourage clarity over cleverness.
• Keep interfaces small, names specific, and responsibilities narrow by default.
• Use boundaries — both architectural and social — to prevent complexity from leaking across the system.

Create Safe Spaces for Discussion and Learning

Healthy teams surface biases early, not late. They ask hard questions in design reviews, reflect together after launches, and encourage curiosity over defensiveness. Pairing different personality types — perfectionists with pragmatists, cautious thinkers with bold innovators — often reveals blind spots and balances extremes.

And most importantly: foster a culture where challenging an idea doesn’t feel like challenging a person. That’s how we move from defending complexity to dismantling it.

Use Structured Decision-Making Tools

Cognitive shortcuts often lead us to pick familiar tools or repeat past solutions without critical evaluation. Checklists, decision matrices, or even just a shared “consider before you abstract” checklist can help you avoid these defaults and consider meaningful alternatives.

Rely on Data, Not Just Intuition

Opinions are loud, but data is quieter and more reliable. When deciding whether to refactor, optimize, or adopt a new tool, ground the discussion in evidence: performance metrics, usage data, real-world constraints. Knowing the difference between a real pattern and a coincidental one is a superpower — and statistics are the map.

Apply Occam’s Razor

Finally, when two solutions solve the same problem equally well, choose the simpler one. The one with fewer assumptions, fewer moving parts, and fewer things that can go wrong. Simplicity isn’t just elegance — it’s strategic clarity.

Final thoughts

Software complexity often looks like a technical problem — but it’s deeply human. It reflects how we think, how we collaborate, and how we cope with uncertainty. Code is written for humans first, machines second — and our brains are the ultimate interpreter. The best software isn’t just technically sound; it’s built by people who understand not only the system, but themselves. With self-awareness, empathy, and clear intent, we can create systems that are not only powerful, but also maintainable, adaptable, and human-friendly.

Cognitive limits, biases, and personal tendencies all influence the way we design and evolve software. They shape how we frame problems, what solutions we reach for, and which trade-offs we accept. Left unchecked, they lead to solutions that don’t quite fit — adding complexity not because the problem demanded it, but because we misunderstood the problem. When we recognize these human influences, we gain the power to catch ourselves — and each other — in the act of unintentionally making things harder. That’s how we move from managing code to managing complexity.

An interface defines how two parts of a system interact. It tells you what you can rely on, what you need to provide, and what you can expect in return. At its simplest, it might be a function signature. At its most complex, it’s an entire service API, an SDK, or a protocol between two teams in different time zones.

We design interfaces constantly, often without calling them that:

• Defining a function or data structure means deciding what’s public and what’s private.
• Splitting an app into modules shapes how features or services communicate.
• Connecting frontend and backend creates a contract for how data flows between them.
• Integrating third-party tools depends on remote APIs, SDKs, and configuration surfaces.
• UI components, design systems, and CLI tools all define interfaces for usage and composition.

Why Interfaces Matter for Complexity

Interfaces are everywhere — some explicit, some implicit — and they shape how we write, test, extend, and reason about our systems. More than just technical artifacts like signatures or schemas, interfaces are how we hide complexity, enforce separation, and communicate intent. The complexity of a system doesn’t just come from how it works internally — it comes from how much of that internal mess others have to understand just to use it. Interfaces are the lever that controls that experience. They’re where complexity either gets absorbed — or spills over. Every time we define or consume an interface, we’re not just connecting code — we’re shaping how people think.

• Interfaces determine coupling
  Poorly abstracted interfaces often expose implementation details or force consumers to know too much. This tightens the coupling between systems and makes changes harder, riskier, and more expensive.

• Interfaces create abstraction boundaries
  They draw the line between what’s inside and what’s outside. A well-encapsulated interface reduces mental load and lets you work with a system without understanding its internals. A bad one forces you to think about too much at once. (More on abstraction)

• Interfaces act as contracts
  They’re promises between parts of the system. The stronger and clearer the contract, the more confidently teams can work independently. Weak or unstable contracts breed uncertainty — and with it, defensive code, extra checks, and over-engineering.

• Interfaces are where complexity compounds
  Especially at team and system boundaries. Misalignment between frontend/backend, client/server, or feature/service often leads to glue code, mismatched assumptions, and integration bugs.

• Interfaces shape how we use a system
  They guide interactions and encode design intent. Clear, consistent interfaces make code easier to use and extend. Confusing ones lead to workarounds, forks, and rewrites.

What Makes an Interface Good or Bad?

Not all interfaces are created equal. Some make systems easy to use, change, and reason about. Others create friction at every step. A good interface reduces complexity — a bad one amplifies it.

Here are some key properties that distinguish good interfaces from bad ones, along with examples that show how they play out in practice.

1. Clarity vs. Ambiguity

Good interfaces are clear in intent and usage. You can tell what they do, what inputs they expect, and what outputs they produce — without reading the internal implementation.

Bad interfaces are ambiguous. They require trial-and-error, reading the source, or asking someone else to understand how to use them correctly.

🧩 Example:

• ✅ func sendEmail(to address: EmailAddress) — clear intent.
• ❌ func process(_ input: Any) — unclear purpose, undefined expectations.

2. Minimal Surface Area vs. Overexposure

Good interfaces expose just enough to do the job — and no more. They present a minimal, focused contract.

Bad interfaces leak internal details or expose too many options “just in case,” increasing cognitive load and coupling.

🧩 Example:

• ✅ analytics.track(event: .productViewed(page: .productPage, id: “123”))
• ❌ analytics.log(name: String, properties: [String: Any], sendImmediately: Bool)

3. Consistency vs. Surprise

Good interfaces behave consistently with the rest of the system. They follow naming, structure, and behavioral conventions that match other components.

Bad interfaces break expectations, introduce some unintended side effects.

🧩 Example:

• ✅ Consistency across the similar functional objects

  let loginViewController = loginCoordinator.start()
  let productsViewController = productsCoordinator.start()
  let profileViewController = profileCoordinator.start()
  

• ❌ Various design patterns across the similar objects

  loginRouter.goToPasswordReset()
  products.startFlow(in viewController: parentViewController,
                    options: [.modalPresentationStyle(.fullScreen)])
  let profileViewController = profileCoordinator.start()
  

4. Stability vs. Volatility

Good interfaces are stable over time. They evolve carefully and intentionally.

Bad interfaces change frequently — even in backwards-incompatible ways — forcing every dependent component to adapt.

🧩 Example:

• ✅ A versioned API with deprecated fields clearly marked.
• ❌ A shared protocol that changes weekly, breaking multiple modules downstream.

5. Encapsulation vs. Leakage

Good interfaces hide complexity behind a clean surface.

Bad interfaces force consumers to know too much about what’s behind the curtain — exposing implementation details, states, or dependencies that don’t belong outside.

🧩 Example:

• ✅ Session.start()
• ❌ Session.prepare(userContext: UserContext, cache: CacheStore, options: [String: Any])

6. Context-Appropriate vs. Internally Driven

Good interfaces reflect the mental model of the consumer. They speak the language of the problem domain, not the internal implementation.

Bad interfaces mirror how the system is built rather than how it’s used — exposing low-level or irrelevant details to the caller.

🧩 Example:

• ✅ Cart.totalPrice(in currency: CurrencyCode)
• ❌ Cart.getAmounts(applyTax: Bool, applyDiscount: Bool, useCachedRate: Bool)

7. Focused Responsibility vs. Overgeneralization

Good interfaces do one thing well. They’re easy to explain in a sentence.

Bad interfaces try to be everything to everyone — and end up doing none of it cleanly.

8. Ease of Use vs. Defensive Usage

Good interfaces guide the user toward correct usage. They make the easy thing the right thing.

Bad interfaces require defensive code, special flags, or knowledge of edge cases to avoid misuse.

Good interfaces make code easier to read, use, change, and test. They absorb complexity — so it doesn’t spread. Bad interfaces do the opposite: they force complexity outward, making every consumer deal with it.

That’s why interface design isn’t just a technical detail. It’s one of the highest-leverage tools we have for managing complexity at scale.

Mitigating Complexity with Better Interfaces

Interfaces are one of the most powerful tools we have for managing complexity — but only if we design and evolve them with care. A poorly thought-out interface pushes complexity onto the user, while a good one hides it, clarifies intent, and enables safe, confident usage. Below are practical guidelines to help you shape interfaces that reduce friction, lower cognitive load, and evolve gracefully over time.

• Keep them minimal
  Expose only what’s necessary. The smaller the interface, the less there is to understand, misuse, or change. Simpler interfaces are easier to learn, test, and maintain.

• Be consistent
  Use consistent naming, parameter order, data shapes, and error handling across all your interfaces. Familiar, predictable patterns reduce mental effort and speed up comprehension.

• Separate concerns
  Avoid multipurpose interfaces. Each interface should have a focused responsibility — doing one thing well. Separation enables reuse without unintended coupling.

• Invest in documentation
  Choose clear, intention-revealing names, types, and constraints so the interface explains itself at a glance. Self-documentation helps, but it’s not enough — especially for shared or public interfaces. Clarify not just what the interface does, but why it exists and how it should be used.

• Design for evolution
  Interfaces tend to stick around. Design them with future growth in mind. Use techniques like deprecation, optional parameters, clear versioning, and compatibility layers to support change without disruption.

• Use deep, not shallow modules
  Favor interfaces that offer high value with minimal surface area. A deep module hides complexity behind a simple API (e.g., a start() method that kicks off an entire flow), while a shallow one forces the consumer to manage internals themselves.

• Fail loudly and early
  If an interface is used incorrectly, it should produce a clear error — not silently fail or allow invalid input to slip through. Defensive code at the boundary reduces bugs downstream.

• Stabilize contracts
  Once an interface is shared — especially across teams or services — treat it like a contract. Changing it carelessly creates ripple effects that increase complexity everywhere it’s used.

• Design for the consumer, not the implementation
  Structure the interface around how people use it — not how the system stores or calculates data. Consider the consumer’s mental model, what they know, and what will make their job easiest.

• Create collaborative design processes
  Interfaces shouldn’t be designed in isolation. Run interface or API reviews that include stakeholders from both sides of the boundary — those who build it and those who use it. This reduces the chance of costly mismatches.

• Test interfaces from the outside
  Use integration or contract testing to validate that your interfaces are usable and resilient. If a consumer test is hard to write or read, it may signal that the interface needs simplification.

But abstraction is also a double-edged sword. When done poorly — too early, too generically, or in the wrong context — it can increase complexity instead of reducing it. Layers of indirection, leaky contracts, mismatched models, and unnecessary generalization all make the system harder to reason about. This article explores how abstraction helps and harms, how to recognize bad abstractions, and how to build the right ones for the problems at hand.

Modeling Reality

Abstractions are all around us — not just in software, but in how we perceive and understand the world. In the physical world, we work with layers of abstraction to make sense of complex systems. At the smallest scales, we study atoms, molecules, and cells. At higher levels, we talk about tissues, organs, organisms, and ecosystems. In physics, we might go from quantum particles, to materials, to human-scale mechanics, all the way up to planetary and galactic systems. We use different models for each of these layers because it would be overwhelming — and unnecessary — to consider all layers at once. We don’t need particle physics to treat a broken leg.

Abstractions are always adjusted to the context. Consider a country on a map: the same country can be represented in vastly different ways depending on what you’re trying to understand. A political map highlights borders and capitals. A population density map reveals demographic patterns. A topographic map shows terrain. All of these are abstractions of the same reality — but each is tuned for a specific purpose.

Software development follows the same pattern. When we build systems, we are modeling reality. Everything we create — data types, services, app modules, even full architectures — is a model of something. A User data type models a real person (or, more precisely, the aspects of that person that our system cares about). A NotificationService models the process of informing users. An entire app might model a shopping experience, a logistics pipeline, or a healthcare workflow.

These models, like all abstractions, intentionally leave out some details to make the system manageable. What we choose to represent — and what we choose to ignore — is guided by context.

Let’s say we work on a car simulation. We start with the simplest model: the car is just a point moving on a 1D grid. We don’t need more for the beginning. Then we develop our module and add movement controls — acceleration, braking — and simulate inertia. Then we work on the UI: put it to a 2D-space and add size to our moving point. Later, we want to make it even closer to reality, so we add visual components: shape, color, orientation. Eventually, we might simulate full 3D physics, engine temperature, tire wear, or even fuel type. Each version of the simulation is a valid model of a car adjusted to a specific context. As the context evolves the model changes as well.

The art of abstraction lies in making two essential decisions: first, choosing the right context — understanding what question we’re trying to answer and how we intend to work with the abstraction; and second, deciding which details are important enough to include and which can be safely left out, based on that chosen context.

When we get those two things right, abstraction reduces complexity. When we don’t, it often does the opposite.

Common Abstraction Pitfalls

Even though abstraction is a tool for managing complexity, it can easily become a source of complexity itself when misapplied. Here are some of the most common ways abstractions go wrong.

1. Wrong Level of Abstraction

An abstraction that operates at the wrong level can either oversimplify or overcomplicate the problem. When it’s too shallow, it omits important details and fails to support real-world usage. When it’s too deep, it tries to cover every possible scenario — cluttering the interface with edge-case handling, parameters, and configuration options that most consumers don’t need.

This often stems from a desire to generalize too early — seeing two similar bits of logic and merging them into a shared abstraction. But surface-level similarity doesn’t always mean shared purpose. The result is a brittle abstraction that satisfies no use case fully, and becomes harder to evolve as requirements change.

You’ll often feel this pain when trying to extend the abstraction. Suddenly, the once-“generic” solution starts accumulating switches, conditionals, or awkward workarounds — all symptoms of a model that no longer fits.

Signs this is happening:

• The abstraction claims to be general-purpose but only supports a subset of use cases in practice.
• It contains branching logic or edge-case handling that grows over time.
• It’s difficult to use correctly without reading the implementation.
• It feels like a compromise: not expressive enough for one case, too verbose for another.
• Every time a specific use case changes, you’re forced to touch the abstraction.
• You find yourself thinking: “This would be easier if each case had its own implementation.”
• You’re writing more code to support the abstraction than to solve the original problem.
• Refactoring it feels risky because it affects many unrelated parts of the codebase.

Examples:

• A Shape protocol that assumes all shapes have corners — then you need to add a Circle, and everything breaks.
• A BaseViewModel with dozens of hooks to accommodate multiple screens, where each screen uses only a few of them — and often in incompatible ways.
• A Config object that tries to hold all environment settings, screen parameters, and user preferences in one place — but becomes unreadable and impossible to safely evolve.
• A FormField abstraction designed to cover every kind of input (text, number, date, dropdown, toggle), but the API becomes so bloated with configuration flags that each new field type needs multiple if-statements to function properly.

✅ Hint: Before abstracting, ask: Are these really the same thing? Or are they just accidentally similar right now?

2. Redundant Abstraction

There are many cases where an abstraction is created without a real need for one. This often happens in the form of premature abstraction — introducing layers before real duplication, variation, or friction appears. The intent may be to “do it right from the start” or to make future changes easier. But in reality, these abstractions are usually based on guesses — guesses about what might be reused, or what could change. The problem is, the future rarely plays out exactly as we expect.

Another common case is abstraction for the sake of “clean” architecture. We introduce protocols, wrappers, services, and layers to align with a favorite pattern or to satisfy a theoretical purity — not because the problem demands it. These layers create indirection, fragmentation, and mental overhead. Eventually, the cost of navigating the abstraction outweighs the benefits it provides.

Signs this is happening:

• The abstraction is only used once — or has no meaningful reuse.
• It’s harder to onboard someone into the abstraction than to understand the actual logic.
• You use passthrough functions, parameters, or entire layers that don’t add value.
• You often bypass the abstraction or re-implement similar functionality elsewhere.
• You can’t explain why it exists without saying “just in case” or “it might be reused.”
• Understanding the code requires jumping between multiple files and types.
• The abstraction has more structure than substance — its logic is trivial or nonexistent.

Examples:

• A Logger protocol introduced to allow log swapping — but no one ever uses any implementation other than ConsoleLogger.
• A StorageManager class that wraps UserDefaults with identical method signatures, adding no behavior beyond delegation.
• A ViewModelProtocol created for testability, but only one concrete implementation exists — and the test uses the real one anyway.
• A NetworkClient interface introduced early in the project, even though only one backend is used and no alternative is planned.
• A Coordinator protocol with no shared responsibilities, implemented by each screen with unrelated navigation logic.

✅ Hint: Prefer concrete clarity over abstract purity.

3. Leaky Abstractions

A leaky abstraction is one that fails to fully hide the complexity it was meant to encapsulate. From the outside, the abstraction should offer a clean, predictable interface — shielding its users from internal details. But with a leaky abstraction, you find yourself digging into the implementation just to understand how to use it correctly or safely.

Joel Spolsky’s Law of Leaky Abstractions puts it clearly: “All non-trivial abstractions, to some degree, are leaky.” While some degree of leakage may be inevitable, it becomes a real problem when the abstraction pretends to simplify something but still forces you to understand what’s underneath. Instead of reducing cognitive load, it increases it — with a false sense of simplicity.

Leaky abstractions break encapsulation, increase coupling, hurt modularity, and frustrate developers trying to reason about the system.

Signs this is happening:

• You need to understand internal behavior or edge cases to use the abstraction correctly.
• The abstraction exposes implementation-specific concepts in its API.
• You frequently open the source to “see what it’s doing under the hood.”
• You find yourself passing raw internals (like file paths, query strings, or framework-specific data) through an otherwise abstracted interface.
• You must remember undocumented caveats or usage patterns to avoid breaking things.
• You get unexpected bugs from valid usage — because how it works matters more than what it claims to do.
• The abstraction doesn’t match the mental model it tries to present.

Examples:

• A NavigationRouter abstraction that wraps navigation logic but still requires you to consider whether you push to NavigationController or present something modally.
• An API client abstraction that handles requests (completely type-agnostic) but requires you to manually serialize and deserialize the payloads (considering exact response types with specific structure) — defeating the purpose of the abstraction.
• A Theme object that claims to encapsulate styles but exposes underlying UIKit values (like fonts and colors) without consistent mapping to the design system.
• A form validation abstraction that delegates to internal logic — but users must still know how validation errors are structured or displayed to use it effectively.

Principles for Better Abstractions

Abstractions are not inherently good or bad — their quality depends on how well they fit the problem they’re trying to solve. When used appropriately, they reduce cognitive load, isolate complexity, and improve code reuse. When misused, they obscure logic, create fragility, and slow teams down. The key is to approach abstraction deliberately and iteratively — not dogmatically.

Here are some practical guidelines to help you design and evaluate abstractions more effectively:

• Let abstractions emerge
  Don’t invent abstractions too early. Let them arise naturally from repeated patterns or real-world friction. Extraction after the fact leads to better-aligned interfaces.

• The name matters
  A precise name forces clarity. If you struggle to name your abstraction, you probably haven’t figured out what it really does — and others will struggle to use it correctly.

• Design for now, not for maybe
  Build the abstraction that solves today’s problem well. Reuse should be a byproduct of clarity, not a justification for guessing what the future might need.

• Hide what doesn’t need to be known
  Keep the interface minimal. Expose only what’s essential, and shield consumers from irrelevant complexity.

• Utilize the separation of concerns principle
  If your abstraction is doing too much, it’s probably doing too little well. Split it into focused, single-purpose units.

• Design by subtraction
  Ask yourself: “What can I remove and still have this work?” Good abstractions tend to get simpler over time, not more complex.

• Avoid passthrough layers
  If an abstraction only delegates without adding meaning or behavior, remove it. Extra layers should earn their keep.

• Reassess regularly
  Abstractions that were once useful can become barriers. Revisit them when requirements change — don’t let outdated design decisions linger.

• Don’t fear repetition
  A little duplication is often better than the wrong abstraction. Try inlining and duplicating the logic — you might find it’s clearer. If not, re-extract with a better understanding.

• If it leaks — rethink it
  A leaky abstraction is often a sign of the wrong boundaries or misunderstood complexity. Either rework it, or eliminate it.

• Document the purpose
  Every abstraction should have a reason to exist. If you can’t explain it in one clear sentence, reconsider whether it’s needed at all.

Conclusion

Abstractions are one of the most powerful ways we manage complexity in software projects. By hiding unnecessary details and organizing logic around meaningful concepts, they help us reason about systems more effectively and reduce the cognitive load required to work within them. Good abstractions do more than hide details — they shape how we think, debug, and build. They influence the mental models we form, the questions we ask, and the mistakes we avoid.

Like architecture, abstraction is not something we get right once — it’s something we adapt over time. The best abstractions are responsive, practical, and grounded in the real needs of the system. They reduce local complexity without introducing global confusion. When done well, abstraction becomes not just a technical device, but a strategic tool for building software that’s easier to understand, evolve, and trust.

When the solution doesn’t truly fit the problem it’s trying to solve, it introduces friction. Even if the code is well-written or follows best practices, if it doesn’t address the right shape of the problem, it becomes harder to understand, harder to maintain, and harder to evolve.

Causes of Mismatch

There are many ways a solution can become misaligned with the problem it’s supposed to address:

• Suboptimal decisions at the start
  We may choose an ill-fitting solution early on due to time pressure, incomplete information, or lack of experience.

• The problem evolved, but the solution didn’t
  A solution that once worked well may become awkward as requirements or context shift over time.

• Overgeneralization or copy-pasting
  We might borrow a pattern from another part of the app or from industry examples without fully understanding it. Similarity on the surface doesn’t mean the underlying problems are the same.

Signs You Might Be Dealing with a Problem–Solution Discrepancy

Recognizing the mismatch is the first step. Here are some examples:

• You have to frequently explain “why it’s done this way.”
  When working with some piece of logic you need to gather some additional context. The design needs extensive documentation to justify itself.

• You’re writing a lot of glue code, wrappers, or adapters.
  These often appear when the parts don’t naturally fit together — you’re forcing compatibility where there isn’t any.

• You’re breaking abstractions or layering rules.
  For example, reaching deep into another layer’s details, using downcasting, adding one-off flags, or relying on fragile type checks — all signs that the abstraction isn’t holding up.

• The code feels unintuitive or awkward.
  Even if it “technically works,” it doesn’t feel natural or straightforward. You or your teammates might avoid touching it unless absolutely necessary.

Why Recognizing Mismatch Is Hard

Recognizing a mismatch isn’t always easy. We tend to be biased toward what already exists (more about the biases in the following articles). Familiarity can be misleading — just because we understand a tool doesn’t mean it fits the problem. In high-pressure environments, we often optimize for short-term speed, making it easier to move forward with a known (but imperfect) solution than to pause and reconsider.

What makes this even harder is that problems often evolve gradually. We may not notice how much the current solution has drifted away from what the problem really requires — until the weight of complexity becomes too heavy to ignore.

Consequences of a Mismatch

Imagine you try to use a spoon to cut instead of a knife. Technically, it works — you can apply enough pressure and eventually get the job done. But it’s slow, awkward, and prone to mistakes. To make it more effective, you might start modifying the spoon, developing special techniques for using it, or building accessories to help stabilize what you’re cutting.

The more you try to improve the wrong tool, the more complexity you add. You end up with a mess of modifications, documentation, and rituals to support something that was never meant to do the job in the first place.

This is what happens when a solution doesn’t fit the problem: you pay an ongoing cognitive tax. The system becomes harder to understand, harder to explain, and harder to change.

Two Reactions: Redesign or Patch

Once you recognize the mismatch, you’re usually left with two options. One is to redesign the solution from the ground up — to realign it with the actual shape of the problem. This is more difficult and time-consuming, but it typically results in a system that is simpler, more maintainable, and easier to work with in the long run.

The second, more common option is to patch the existing solution. We layer on exceptions, conditionals, adapters, and tweaks to make it “work.” But every patch is a small deviation from clarity, and over time, these patches accumulate. Eventually, the structure becomes difficult to reason about, and changes require more and more mental effort.

Although redesigning feels expensive upfront, it often saves time and complexity in the long term. In contrast, the patching approach is a form of debt — it accumulates quietly and compounds with every change.

How to Avoid It

• Understand the problem deeply before jumping into the solution.
  Rephrase it in multiple ways, sketch alternatives, and discuss with teammates. Don’t settle for the first idea that seems to work.

• Start with the simplest viable shape.
  Avoid overengineering or premature abstraction — you can always refactor once the problem is better understood.

• Design by subtraction.
  After your first draft, ask: What can I remove without breaking the essence of the solution?

• Be pragmatic — validate fit over elegance.
  The best solution is not always the most elegant one. Sometimes the right shape is the boring one that just works.

• Try to find several solutions.
  Exploring a few directions allows you to compare trade-offs and better understand what matters most in your context.

• Regularly revisit assumptions.
  What worked before may not work now. Be willing to let go of solutions that no longer serve the problem.

Agile architecture

Misalignment doesn’t only affect individual pieces of logic — it can also affect the architecture of an entire module or even the whole app.

In modern development, we typically follow Agile methodologies. We start with a general idea and evolve the product incrementally, discovering the path as we go. This approach works well for products, but it also introduces a challenge: our architecture must adapt just as fluidly. If the system architecture is rigid or overly predetermined, it inevitably becomes misaligned with the evolving needs of the product.

That’s why architecture needs to be agile too. It must be designed with evolution in mind. This doesn’t mean skipping structure altogether, but rather building in flexibility: making it modular, keeping boundaries clean, favoring composition over inheritance, isolating decisions that are likely to change, and avoiding premature generalization.

Whether it’s called evolutionary architecture, emergent design, or just pragmatic refactoring — the principle is the same: keep your architecture open to change, so it can continue to match the problem it’s meant to solve. This alignment is what keeps complexity from spiraling out of control as your app grows.

Developers spend a large portion of their time reading, navigating, and understanding code — not writing it — so clear structure is essential. A thoughtful distribution of logic reduces the mental effort required to follow the flow of the app, understand responsibilities, and make safe changes. In short, good structure keeps cognitive load low and complexity in check.

Foundational Principles

Clear structure helps reduce complexity — but knowing how to separate and organize code well is not always obvious. As projects grow, responsibilities blur, logic spreads, and it becomes harder to decide where things should live. Fortunately, there are a few foundational principles that serve as practical guidelines for distributing logic in ways that reduce cognitive load and improve maintainability. These principles can be grouped into three categories, each addressing a different aspect of structure: limiting responsibilities, deciding what belongs together or apart, and controlling how much code knows about other code. Together, they help us shape systems where each part is easier to understand, reason about, and evolve — the very qualities that keep complexity under control.

1. Limiting Responsibilities: What should this code be responsible for?

Separation of Concerns (SoC) is about dividing the system into parts that focus on different areas — such as UI rendering, business logic, networking, or persistence. When different responsibilities are mixed together — for instance, a view controller that fetches data, parses it, formats it for display, updates the UI, and manages navigation — the result is code that’s harder to reason about, harder to change, and more error-prone. SoC helps reduce complexity by ensuring each part of the system has a clear and focused role.

The Single Responsibility Principle (SRP) takes this idea to a more granular level, guiding how we design individual types and functions. Each class or function should have one reason to change. This helps isolate concerns and reduces the risk of unintended side effects during refactoring.

In practice, we apply these principles at multiple levels of abstraction:

• At the app level, we separate responsibilities across feature modules or sections of the app. For example, the onboarding flow, user profile, and checkout process might each live in their own isolated modules with clear ownership and dedicated navigation flows.

• At the functional layer, we move responsibilities into dedicated roles, for example:
  • View controllers to handle UI rendering and user interaction.
  • View models - to manage presentation logic and data preparation.
  • Coordinators (or flow controllers) - to control navigation and screen transitions.
  • Services - to handle specific tasks like networking, analytics, persistence, or remote configuration.
• At the function and data type level, we apply SRP by avoiding bloated types and breaking down logic into focused pieces:
  • A function that parses and validates input might delegate formatting to a separate utility.
  • A data model might be accompanied by a display model that formats its data for presentation.
  • An API client should only concern itself with networking — not with how the data will be shown or stored.

These decisions aren’t always black and white. There’s a trade-off between separating responsibilities and over-fragmenting the codebase. If separation is taken too far, you may end up with many tiny components that are hard to trace and understand in context — increasing rather than reducing cognitive load. The key is clarity: split responsibilities when doing so makes the system easier to understand, test, and evolve — not just to follow a rule. Thoughtful separation leads to a codebase where each part does one thing well and is easy to reason about in isolation.

2. What Belongs Together: Which pieces of logic should be grouped, and which should be separated?

When making decisions about grouping or separating logic — whether it’s functions, data types, functional layers, or entire feature modules — a few helpful questions can guide you:

• Do you mostly need to keep the parts together in mind?
• Are the parts normally used together?
• Is it hard to understand one without the other?
• Do they have shared state, dependency, or data model?
• Do they manipulate the same object or concept?
• Do they perform different operations?
• Do they have different levels of detail or abstraction?
• Do they have a semantic relationship (e.g., general vs. specialized behavior)?

While responsibility defines what a piece of code should do, cohesion and coupling help us decide how things should be grouped and how they should interact. These principles are essential in shaping systems that are easy to navigate and evolve — they reduce the number of concepts a developer must juggle when working within a codebase.

Cohesion refers to how closely related the functions and data within a module, type, or file are. High cohesion means everything inside serves a common purpose — making the module easier to understand and reason about. Low cohesion, by contrast, is a red flag: it suggests that unrelated logic has been lumped together, often out of convenience. For example, a UserManager that handles user authentication, profile formatting, local caching, and UI updates is trying to do too much. Splitting these into more focused units — like an AuthService, UserProfileFormatter, or CacheManager — improves clarity and testability.

Coupling measures how dependent one piece of code is on another. Tight coupling means that changes in one component may require changes in another, which makes the system brittle and harder to maintain. Loose coupling enables components to evolve independently. For instance, if your view model is directly instantiating and managing its dependencies (e.g., networking code, data models), it becomes tightly coupled to them. Introducing abstractions like protocols and dependency injection reduces that coupling, allowing different parts of the codebase to be reused, tested, and replaced in isolation.

You can see these principles applied at multiple levels:

• In feature modules: Grouping all the files related to a single feature — its views, view models, services, and navigation logic — into one place increases cohesion. This minimizes the mental jumps needed to understand or change a feature.

• In types: A model object should only contain logic relevant to its role. Avoid putting formatting, validation, and networking logic into a single struct or class.

• In functions: A function that handles user input should not also log analytics or trigger navigation. Keeping related behavior together, and unrelated behavior separate, leads to smaller, more focused functions that are easier to understand and reuse.

High cohesion and low coupling work together to reduce cognitive load. They localize logic, clarify intent, and limit the surface area affected by change — all of which make a codebase feel more navigable and less overwhelming.

3. Limiting Knowledge: How much should one part of the system know about another?

The third group of principles focuses on visibility and dependencies — in other words, how much knowledge one part of the system has about another. The less a component needs to know about the internals of others, the easier it is to understand and change in isolation. This group includes encapsulation, information hiding, and the Law of Demeter.

Encapsulation is about hiding internal implementation details behind well-defined interfaces. When we encapsulate properly, other parts of the system don’t rely on the internal mechanics of a component — only on its public contract. This allows us to refactor the internal workings without breaking everything that depends on it. For instance, a DataStore might expose simple methods like save() and load() while hiding how the data is serialized or where it’s stored.

Information hiding extends this idea to a broader scale. It’s the principle of not exposing more than what’s needed. A module shouldn’t leak internal types, intermediate states, or implementation-specific details unless absolutely necessary. This keeps boundaries clean and reduces the chance of other components forming hidden dependencies.

The Law of Demeter (“don’t talk to strangers”) advises that code should only interact with objects it directly owns or receives. This prevents “train wreck” code like user.profile.settings.theme.name, which exposes deep internal structures and creates tight coupling. Instead, higher-level objects should expose what’s needed explicitly. For example, user.displayThemeName is much easier to consume and hides the internal structure of the user profile.

These principles help reduce complexity by minimizing the amount of knowledge a developer needs to understand or safely modify a piece of code. When modules and types act as black boxes with clear inputs and outputs, it becomes easier to reason about behavior, write tests, and change internals without fear of unintended consequences.

Applying the Principles in Practice: Modularisation

Splitting an application into multiple modules or components is one of the most effective ways to reduce complexity in larger projects. By breaking the system into logical units — such as Authentication, Payments, UserProfile, or DesignSystem — we create bounded contexts that are easier to understand, maintain, and evolve independently.

This practice directly applies principles like separation of concerns (each module handles its own domain), single responsibility (modules have one clear purpose), encapsulation (internal details are hidden behind module interfaces), and low coupling (modules depend only on well-defined contracts, not each other’s internals).

A well-modularized project allows teams to work in parallel, isolate bugs, write better-targeted tests, and reduce the mental overhead of navigating a massive codebase. Developers can reason about a feature in isolation, without needing to understand unrelated parts of the system. It also enables more controlled dependencies — for example, UI might depend on DesignSystem, but DesignSystem never depends on UI, keeping the dependency graph clean and directional.

Modularization doesn’t just reduce build times or improve testability — it helps shape the architecture in a way that reflects the real structure of the domain. This alignment lowers complexity and boosts confidence in the codebase. Also by applying decomposition we split one piece (an app or a feature module) into smaller and more digestable pieces.

Applying the Principles in Practice: Project structure

The way we organize files and folders in a project is a direct reflection of the principles we’ve covered: separation of concerns, single responsibility, cohesion, coupling, and encapsulation. A thoughtful physical structure supports these ideas and helps reduce complexity by making the system easier to navigate and understand.

A common choice is between layer-based and feature-based structures. Layer-based organization groups files by type — for example, all views in one folder, all services in another. While this can work in simple projects, it often forces developers to jump across the codebase to trace a single feature. A feature-based structure, on the other hand, keeps related logic together — such as placing ProfileView.swift, ProfileViewModel.swift, and ProfileService.swift within a Profile/ module. This approach increases cohesion and reduces the mental effort required to understand and modify a feature.

In Swift, it’s also important to be mindful of how we use extensions. It’s common to break a type into multiple files using extensions — for example: User.swift defines the core model, User+Decoding.swift adds conformance to Decodable, and User+Display.swift contains UI formatting logic. While this can improve clarity when used carefully, excessive fragmentation leads to poor cohesion and makes it harder to form a complete mental model of the type.

Files like Utils.swift, Helpers.swift, or Extensions.swift are another frequent sign of structural issues. These vaguely named containers often become dumping grounds for unrelated logic, violating principles like single responsibility and information hiding.

Ultimately, good physical structure aligns with how we think about the system. It helps developers find what they need, understand the scope of changes, and maintain the codebase with confidence.

Applying the Principles in Practice: Refactoring a function

Here is the function that is triggered when a deep link arrives to the app. It’s quite verbose, so don’t dig into its details now.

Let’s see what the function does on a high level:

Ideally these high-level operations should be the only things we see inside the function on this level of abstraction. The rest of the logic should be removed into the subfunctions. Let’s check then what is this logic in-between the high-level manipulation:

The first part: Manipulating the URL components we can directly move to a subfunction:

What are the exact operations we are doing here:

Should we move these two operations to the next abstraction level and separate them into the subfunctions? Probably… But before doing this let’s check the object of manipulation within the fucntion:

Even though we work with the query, path and host, technically, URLComponents is a shared state for these different operations. We manipulate the same object on the same level of abstraction, so if we split the function we will need to path the data in and out, that will complicate the understanding.

So we are leaving this preprocessedURL()-function as it is, without splitting it further. It is not tiny, but seems comprehensible enough.

Back to our root-function. We moved the preprocessing logic out. Should we do the same with another non-high-level part?

Let’s explore this option…

…looks neat.

And the last thing left is this tracking function:

It doesn’t belong to the high-level operations we perform here. Instead it’s a side-effect of opening a deep link. Every time we open a Deep Link we want to track it. So these 2 operations (passing a deep link further to open and tracking it) are related to the same event. So it makes sense to encapsulate this logic and separate it to a subfunction (that can be reused further if a deep link comes from somewhere other than the external URL: push notification, home screen widget or a Siri intent.):

Our root function became much simpler, more straightforward and comprehensible.

We decomposed it, separated different level of abstractions, considered what belongs to each other and what doesn’t and even thought about some possible future improvements. Now it’s much easier to reason about this logic and if needed get deeper end explore the details.

Conclusion

Thoughtful code and logic distribution is one of the most effective ways to manage complexity in software projects. It shapes how easily developers can understand, navigate, and evolve a system. When structure reflects responsibility, cohesion keeps related pieces close, and visibility is properly constrained, the codebase becomes less like a maze and more like a well-marked map. The clearer the layout, the less mental effort is needed to get things done — and the more confident we can be when making changes. In the long run, it’s not just what the code does that matters, but how it’s organized — because structure is what makes complexity sustainable.

When we think about complexity in software systems, our minds often jump to architecture diagrams, distributed systems, or multi-threaded concurrency nightmares. But in reality, complexity usually creeps in quietly, through small, seemingly insignificant choices: a deeply nested condition, a vague function name, a misused abstraction. It can lead to the death by a thousand paper cuts — no single decision sinks the system, but the accumulation wears it down, slows progress, and makes change harder than it should be.

Poor Naming

Naming is one of the most powerful tools we have as developers — and one of the easiest to misuse. When names are vague, overly generic, or misleading, they turn code into a puzzle. A variable called data, a function called handle(), or a class named Manager tells us almost nothing about what these things do or are. In mobile development, it’s common to stumble upon things like InfoView, HelperClass, or process() — labels that beg the question: what info? which helper? process what?

Poor naming forces readers to dig for context, scanning other parts of the code to figure out what something means. It increases the time it takes to understand the logic and decreases confidence when making changes. Worse, it creates a false sense of understanding — a name like updateUI() might sound harmless until you realize it’s triggering network calls and state changes under the hood.

Good names reveal intent. A function called fetchUserProfile() or a type called OnboardingStepViewModel communicates its purpose directly, without requiring comments or detective work. When names obscure the real purpose or behavior of code, it becomes harder to reason about the system as a whole. Understanding what each piece does, how it fits with others, or where responsibility lies becomes a constant cognitive burden. Over time, the system becomes fragile not because it’s technically flawed, but because it’s semantically incoherent. Clear, purposeful naming is the first step toward a codebase that’s easy to read, maintain, and grow.

Cyclomatic complexity

High cyclomatic complexity is often a sign that a function is trying to do too much. It means the number of distinct paths through the code is high — often due to excessive branching with if, switch, guard, or complex nesting of conditions. While technically it might still “work,” reading it feels like navigating a maze. You can’t simply follow the logic top to bottom; instead, your mind has to simulate conditions, jump between branches, and keep a mental stack of possible outcomes.

A high-complexity function resists change because each small edit might ripple through a dozen logic paths. Bugs hide in obscure branches. Unit tests become hard to write or incomplete. The solution is not to avoid branching altogether, but to isolate it. Break down decision logic into smaller, testable functions. Favor early returns and reduce deep nesting. Refactor complex conditionals into named booleans or even strategy objects. The goal isn’t to chase a number — it’s to shape the code so that reasoning about it becomes linear again.

More complex:

func doSomething(x: Int) -> Int {
    let y = x + 10
    if y > 0 {
        return y
    } else {
        return 0
    }
}

Less complex:

func doSomething(x: Int) -> Int {
    let y = x + 10
    return y
}

Sometimes this complexity is essential (inherent to the problem), so we cannot do much with it. The 2 funtions in the previous example just do different things.

But in other cases we can do some changes to minimise cyclomatic complexity.

More complex:

func handleNotification(_ type: String, isUserLoggedIn: Bool) {
    if type == "message" {                    
        if isUserLoggedIn {
            openMessages()
        } else {
            showLoginPrompt()
        }
    } else if type == "promo" {
        showPromotion()
    } else if type == "alert" {
        showAlert()
    }
}

(cyclomatic complexity = 5)

Less complex:

func handleNotification(_ type: String, isUserLoggedIn: Bool) {
    switch type {
    case "message":
        handleMessage(isUserLoggedIn)
    case "promo": 
        showPromotion()
    case "alert":
        showAlert()
    default:
        break
    }
}

func handleMessage(_ isUserLoggedIn: Bool) {
    isUserLoggedIn ? openMessages() : showLoginPrompt()
}

(cyclomatic complexity = 3 + 2)

Even though the overall complexity of this piece of logic remained the same we split it into 2 functions and made it more digestable. As in most cases you don’t need to consume it all at once. Moreover we got a better separation of concerns; and 2 small functions are easier to test then one big one.

It’s usually considered that when a function has more than two or three returns, it’s a sign that the complexity is too high and refactoring is suggested. With complexity more than 10, a linter normally shows a red flag.

Nesting level

Nesting level is something we can fully control as developers. In the following example we have 3 levels of nested types: PaymentConfiguration, Entry, and Content.

public struct PaymentConfiguration {
    
    public struct Entry {
        
        public enum Content {
            case modal(PaymentContext)
            case deepLink(DeepLinkContext)
        }
                
        public let title: String
        public let content: Content
        
        public init(title: String, 
                    content: Content) {
            self.title = title
            self.content = content
        }
    }
        
    public let entries: [Entry]
        
    public init(entries: [Entry]) {
        self.entries = entries
    }
}

The cognitive load of such solution high as for each nested structure you need to keep the context of its parent (or even grandparent) in mind. You deal with the Content, but you will likely need to consider Entry and maybe even PaymentConfiguration for the full context. The cognitive contexts of them overlap:

So in this case it’s probably easier to split them into a separate data types, even if it looks more verbose in terms of naming.

public struct PaymentConfiguration {
        
    public let entries: [PaymentConfigurationEntry]
    public init(entries: [PaymentConfigurationEntry]) {
        self.entries = entries
    }
}

public struct PaymentConfigurationEntry {
            
    public let title: String
    public let content: PaymentConfigurationEntryEntryContent
    public init(title: String,
                content: Content) {
        self.title = title
        self.content = content
    }
}

public enum PaymentConfigurationEntryEntryContent {
    case modal(PaymentContext)
    case confirmedDeepLink(DeepLinkContext)
}

This way the contexts don’t overlap:

There might be some exception like using nested structs and enums as name spaces.

public enum AccessibilityIdentifiers {
    
    // MARK: - AboutThisApp
    
    public enum About {
        public static var view = "view"
        public static var list = "list"
        public static var tour = "tour"
        
        public enum Legal {
            public static var view = "view"
            public static var terms = "legal"
            public static var copyrights = "copyrights"
            
            public enum Copyrights {
                public static var view = "view"
                ...
            }
            ...
        }
        ...
    }
}

So it can be used like AccessibilityIdentifiers.About.Legal.copyrights.

But be careful with it, it only works when you don’t need to get inside this nested types, which is the case for constants like Accessibility Identifiers. If the types require instantiation or even some logic (like the previous example with AboutThisAppConfiguration), you will need to ocasionally take a look inside it. Hence no nesting is suggested in those cases.

Number of parameters

Functions with too many parameters often signal a deeper design issue. They might be taking on multiple responsibilities, or they’re being forced to know too much about their environment. From a cognitive standpoint, each parameter is a fact the reader must keep in mind while understanding the function. As the number grows, it becomes harder to mentally simulate the behavior, trace data flow, or confidently make changes.

One way to address this is by grouping related parameters into meaningful data structures — for example, bundling latitude, longitude, and altitude into a Location object, or firstName, lastName, and email into a UserProfile. This not only simplifies the function signature, but also communicates the conceptual relationship between the parameters.

More complex:

public func trackEvent(formId: String,
                       formStep: String,
                       formStatus: String,
                       transactionId: String?,
                       formOutcome: String?,
                       formType: String?) {
    ...
}

Less complex:

public func trackEvent(content: EventContent) {
    ...
}
    
public struct EventContent: Equatable, Sendable {
    public let formId: String
    public let formStep: String
    public let formStatus: String
    public let transactionId: String?
    public let formOutcome: String?
    public let formType: String?
} 

This reduces the number of entities you need to keep in mind when working with the function.

In other cases, if a function is doing too much and therefore needs too much context, it might be time to split it into smaller, more focused pieces. Reducing parameter count improves readability, testability, and long-term maintainability.

Complex conditions

Complex conditions may be completely unreadable:

if (yourFeatureToggleState == .enabled &&
    (numberOfLaunches >= configuration.minimumRequiredLaunches) ||
    (currentDate >= nextPromptDate &&
    applicationVersion != latestVersionWithAlert)) {
    attemptToShowAlert(in: window, completion: completion)
}

A better approach: break them into logical steps, assign parts to descriptive boolean variables, use those variables to make the condition self-explanatory:

let featureIsActive = yourFeatureToggleState == .enabled
let enoughLaunches = numberOfLaunches >= configuration.minimumRequiredLaunches
let dateVersionConditionMet = (currentDate >= nextPromptDate &&
    applicationVersion != latestVersionWithAlert)


if featureIsActive && (enoughLaunches || dateVersionConditionMet) {
attemptToShowNativeRating(in: windowScene, completion: completion)
}

Nested if

Nested if-conditions (which are a specific case of increasing cyclomatic complexity) deserve a separate mention, as it’s one of the most widely spread anti-pattern. Usually you can quite easily simplify it:

More complex:

if cardIds.count > 1 {
    cardDismissHandler()
} else {
    if viewController != nil {
        cardDismissHandler()
    }
    delegate?.dismissViewController(at: location)
}

Less complex:

if cardIds.count > 1 || viewController != nil {
    cardDismissHandler()
} else {
    delegate?.dismissViewController(at: location)
}

If your language supports early returns or constructs like guard, you can flatten the structure and improve readability:

More complex:

if let cardId {
    if let element = interaction.element(for: location,
                                         cardId: cardId) else {
        return
    }
} else {
    tracker.trackElements(element,
                          page: analyticsPage(with: productName))
}

Less complex:

guard let cardId, let element = interaction.element(for: insightsLocation,
                                                    cardId: cardId) else { 
    return 
}

tracker.trackElements(element, page: analyticsPage(with: productName))

Magic Numbers and Strings

Magic numbers and strings refer to hardcoded values that are used directly in the code without any explanation of their meaning or purpose. These “magic” values can significantly increase cognitive load, as developers must either infer their purpose from context or search through the codebase to understand what they represent. This makes the code harder to maintain and extend because any changes to these values require updating them in multiple places, increasing the risk of errors. Using descriptive constants instead of magic numbers or strings makes the code more readable and maintainable, as the intent behind the values is clearer and any future changes can be made in one central location.

More complex:

func calculateDiscount(price: Double) -> Double {
    if price > 100.0 {
        return price * 0.1
    }
    return price * 0.05
}

In the above example, 100.0 and 0.1 are magic numbers. It’s unclear why 100 is the threshold for a discount or what the significance of 0.1 is.

Less complex:

let DISCOUNT_THRESHOLD: Double = 100.0
let STANDARD_DISCOUNT_RATE: Double = 0.05
let PREMIUM_DISCOUNT_RATE: Double = 0.1

func calculateDiscount(price: Double) -> Double {
    if price > DISCOUNT_THRESHOLD {
        return price * PREMIUM_DISCOUNT_RATE
    }
    return price * STANDARD_DISCOUNT_RATE
}

By using constants with descriptive names, the intent of the values becomes much clearer, reducing complexity and making the code easier to understand and maintain.

Implicit Context or Hidden State

Code that relies on implicit context — such as global variables, singleton instances, or shared mutable state — quickly becomes difficult to reason about. When a function depends on or mutates state that isn’t passed in explicitly, it creates invisible dependencies. From the outside, it’s unclear what the function needs to operate correctly or how it might change the state of the system. This makes the code fragile: changing one piece can unintentionally break another, and understanding a function in isolation becomes almost impossible.

This kind of hidden complexity increases cognitive load because it forces developers to mentally reconstruct the larger system state just to understand a small piece of behavior. For example, a UserSessionManager that reads the current user from a global AuthContext may seem convenient, but any changes to the context mechanism or its timing can have unpredictable ripple effects. A better approach is to pass the necessary data explicitly and return any results or changes transparently. This not only makes individual components easier to understand and test, but also encourages better separation of concerns and modular design.

Summary: The Accumulated Weight of Small Decisions

In this section, we explored how seemingly small, low-level decisions in code can significantly increase the cognitive load on developers. These patterns don’t usually break a system outright, but they do make the code harder to read, reason about, and modify. The more of them you allow to creep in, the more they compound, gradually turning simple features into fragile puzzles.

This additive nature of complexity is what makes these small decisions matter. While any one of them might seem harmless, their combined effect is felt most painfully during maintenance or when new features need to be added. Codebases don’t become hard to work with overnight — they erode slowly, one decision at a time.

And this is just the surface. Classic books like Clean Code (Robert C. Martin), Code Complete (Steve McConnell), and Refactoring (Martin Fowler) dedicate entire chapters to these and many other micro-decisions that influence clarity, maintainability, and quality. They’re excellent resources if you want to dive deeper into best practices and learn how to spot and improve problematic code patterns.

As a guiding principle, always remember: code is written for humans first, and machines second. Compilers are fine with cryptic, tangled code — your teammates (and your future self) are not. Writing clean, understandable code is an investment in long-term productivity and peace of mind.

The topic is mostly relevant for ones who spend decent amount of work time reading and maintaining existing code. I know there are developers and teams who produce and ship projects without maintaining them afterward. For them the problem is not so relevant I believe.

What is Complexity?

Complexity is not an absolute measure—it exists on a relative scale. One idea, system, or solution is more or less complex compared to another. The key factor that defines this scale is cognitive load—the mental effort required to understand and work with a concept, system, or solution.

When we describe something as “too complex,” we’re often expressing that we can’t comfortably hold all the moving parts in our head at once. This isn’t a failure of intelligence—it’s a reflection of the natural limits of human cognition.

To understand these limits, it helps to know how our brain processes information. This involves three core systems:

• Sensory memory, which quickly absorbs information from our environment (like reading code on a screen or hearing someone explain an algorithm).
• Working memory, the active space where we process, evaluate, and manipulate information.
• Long-term memory, which stores everything we’ve learned and can be retrieved when needed.

When we solve problems, design systems, or debug code, we’re mostly operating in working memory. It’s where the mental “action” happens.

But here’s the catch: working memory is extremely limited.

According to cognitive science, most people can actively manage only about 5 to 9 chunks of information at a time (a concept famously explored in Miller’s Law, 1956). A “chunk” might be a variable name, a function’s purpose, a dependency between modules, or a user’s intent.

If the code or system we’re working with requires us to hold 15 or 20 different things in mind—branches, side effects, state changes, API constraints—we quickly exceed our cognitive capacity. This is when we start to feel overwhelmed, miss important details, or make mistakes.

Types of complexity

When it comes to human-made systems, there are two types of complexity that are always present in some combination. Some systems are inherently difficult. So difficult that even the interface might look very complex. Take an aircraft cockpit, for example.

There are decades of evolution behind this interface and it is already as easy as it can physically get. We cannot make it simpler without loosing some functionality. This type of complexity is called essential complexity.

In other cases, the system (for instance a device to make coffee) may be implemented differently.

Both of these options bring the same amount of essential complexity. But the second one is much harder to use despite doing the same thing. This extra complexity (of the second approach compared to the first one) is called added or accidental.

What Is Cognitive Load, Really?

Cognitive load comes in three forms:

• Intrinsic load – The inherent complexity of the task itself.
• Extraneous load – The added complexity introduced by poor design, confusing code, or unclear naming.
• Germane load – The effort dedicated to learning, forming mental models, and gaining insight.

Good software design doesn’t aim to eliminate cognitive load — it aims to reduce extraneous load (as we cannot do much with inherent complexity) and support germane load.

That means writing code and building systems that:

• Clearly reflect intent
• Reduce unnecessary nesting or state juggling
• Use consistent patterns and naming
• Separate concerns logically
• …and other things we will discuss in details in the following articles.

In essence: we can’t increase human cognitive capacity, but we can reduce how much of it our code consumes.

Why Does Complexity Matter?

By now, it should be clear: the more complex a system is, the more cognitive capacity it demands — and the harder it becomes to work with. This isn’t just a matter of elegance or personal preference; it affects the very foundations of how we build, scale, and sustain software.

In software engineering, excessive cognitive load has a major impact:

• Complex systems are harder to understand, debug, modify, and maintain. Every added layer of logic or abstraction increases the mental effort required to trace behavior and reason about change. This slows down development and makes even small changes risky.

• The more time new developers spend grasping the codebase, the longer it takes for them to contribute. Onboarding becomes a bottleneck when the mental model of the system is hard to build. Instead of learning the business logic, newcomers spend their energy deciphering internal complexity.

• Scaling is easier with simpler systems. Simple, modular designs can be extended with minimal side effects. In contrast, complex systems resist change—every addition feels like a Jenga move that could topple the whole thing.

• Complex relationships between parts and hidden dependencies lead to unpredictable side effects and bugs. When components are tightly coupled or behavior is implicit, it’s easy to break one thing while changing another. These bugs are often subtle, hard to detect, and expensive to fix.

• Decision-making is slower when we don’t fully understand the system. Whether it’s choosing where to place new code or deciding how to fix a bug, unclear systems create hesitation. Developers are more likely to delay action, over-engineer solutions, or second-guess themselves.

• Communication speed depends on complexity. Complex systems require complex explanations, which leads to more meetings, more documentation, and more back-and-forth. Teams must spend more time in discussions; developers need to explain more to their non-technical colleagues. This communication overhead reduces focus time and slows down collaboration.

• Worse developers’ well-being. Cognitive overload is one of the leading causes of frustration and burnout. Developers feel drained from the difficulty of the problems as well as from the difficulty of the tools and systems they’re forced to work with. Instead of engaging in creative problem-solving, they’re stuck untangling complexity.

That’s why we should care deeply about complexity—and strive to minimize the cognitive load of our solutions. Clear, maintainable systems don’t just improve productivity; they make the work more humane, sustainable, and rewarding.

Measuring complexity.

How can we measure something as abstract as complexity?

Even in the early days of programming, developers sought ways to do it.

1. Lines of code

Counting lines of code is the simplest and oldest approach. It gives a rough sense of the size of a codebase or function. While more lines often correlate with greater complexity, it doesn’t capture how those lines behave—100 lines of well-structured logic may be easier to work with than 20 lines of tangled conditions. Still, this metric is useful for quick comparisons or spotting bloated methods.

2. Cyclomatic Complexity

In the 1970s, a more refined metric emerged: Cyclomatic Complexity—which counts the number of independent paths through a block of code. Each conditional or loop adds a new decision path, increasing the effort required to test, understand, and reason about the code.

For example, this simple function has only one possible path, so its complexity is 1:

func doSomething(x: Int) -> Int {
    let y = x + 10
    return y
}

Introduce a conditional statement, and it jumps to 2:

func doSomething(x: Int) -> Int {
    let y = x + 10
    if y > 0 {
        return y
    } else {
        return 0
    }
}

Loops and additional conditionals further increase complexity, requiring more unit tests and increasing the chance of bugs hiding in untested paths.

3. Halstead Volume

The Halstead Volume metric calculates complexity based on the number of operators and operands in the code. It aims to reflect the mental effort required to understand the code’s structure, not just its control flow. The more unique elements and the more frequently they’re used, the higher the volume—and the higher the cognitive load. It’s especially useful in analyzing how dense or abstract code is, even if the flow is relatively linear.

4. Maximum Nesting Level

This metric tracks how deeply control structures (like if, for, while, etc.) are nested within each other. High nesting levels often signal increased cognitive load, as the reader must keep track of multiple levels of logic simultaneously. Deep nesting also makes it harder to isolate bugs, refactor code, or trace execution paths. Flattening nested logic typically improves readability and testability.

5. Number of Parameters

The more parameters a function takes, the more information the developer must supply and keep in mind. Large parameter lists often indicate a lack of clear abstraction or an overloaded responsibility. Ideally, functions should take only the data they truly need—grouping related values into structs or objects where appropriate. Fewer parameters usually mean simpler, more focused code.

6. Maintainability Index

The Maintainability Index combines multiple metrics — Lines of Code, Cyclomatic Complexity, and Halstead Volume — into a single score from 0 to 100. A higher score suggests that the code is easier to maintain, while lower scores indicate more technical debt and higher risk. It’s useful as a broad health check across a codebase, though it should always be interpreted in context.

MI = MAX(0,(171 - 
     5.2 * ln(Halstead Volume) - 
     0.23 * (Cyclomatic Complexity) - 
     16.2 * ln(Lines of Code)) * 
       100 / 171)

A function may pass this metric numerically but still be hard to understand due to naming, coupling, or domain complexity — so always pair it with qualitative judgment.

Some metrics focus on data structures and object-oriented design:

7. Cohesion

Cohesion measures how closely related a class or module’s internal responsibilities are. High cohesion means the parts work together toward a single purpose, making the code easier to understand and reuse. Low cohesion suggests the class is doing too much—or things that don’t logically belong together—indicating a candidate for refactoring. High cohesion leads to better modularity and lower cognitive load.

One common metric is LCOM (Lack of Cohesion of Methods), which analyzes how many methods in a class access the same fields. If most methods operate on distinct sets of fields, cohesion is low. If they operate on shared fields, cohesion is high.

8. Coupling

Coupling is the degree of interdependence between modules or components. Tight coupling means changes in one module often require changes in others, making the system harder to evolve. Loose (or low) coupling allows components to be developed, tested, and reused independently. Reducing coupling makes codebases more flexible and maintainable in the long run.

To measure it count the number of external classes or modules a given class references (via field types, method parameters, return types, method calls). A popular metric is CBO (Coupling Between Objects).

9. Depth of Inheritance Tree (DIT)

This metric indicates how many levels a class is from the root of the hierarchy. Deeper trees can make it harder to trace behavior, especially if multiple layers override the same methods. While inheritance can promote reuse, overusing it leads to fragile designs and unexpected interactions. Favoring composition over inheritance often reduces complexity here.

To measure it simply count the number of levels from the class to the root of the inheritance hierarchy. E.g., if ViewController → BaseController → UIViewController, then DIT = 2.

10. Response for a Class (RFC)

Response for a Class measures the number of different methods that can be invoked in response to a message sent to an object. A high RFC suggests the class has many responsibilities or exposes too much internal behavior. This can overwhelm the reader and create tight coupling between the class and its clients. Lower RFC typically implies a cleaner, more focused interface.

To measure it count the class’s own methods and any other methods they call (including internal and external calls).

RFC = Number of methods defined in the class + number of methods those methods invoke

11. Number of Own Methods

This metric counts how many methods are defined directly in the class. While not all methods are created equal, a high number can indicate that the class has too many responsibilities or behaviors. Keeping classes small and focused — ideally centered around a single responsibility — reduces the burden on readers and improves reusability.

To measure it count all the methods defined in the class file itself, excluding inherited ones. This includes instance methods, class methods, and private/internal methods. A high count often signals a violation of the Single Responsibility Principle

12. Number of Overridden Methods

Tracking overridden methods helps identify cases where subclass behavior diverges from its parent. A high number may suggest that the base class isn’t providing a stable abstraction or that inheritance is being misused. When overriding becomes the norm rather than the exception, it’s often a sign that composition would be a better fit.

Count methods in the class that explicitly use the override keyword (in Swift or Java), or that match inherited method signatures. High counts may indicate unstable inheritance hierarchies or improper use of inheritance instead of composition.

13. Number of Implemented Interfaces (NOII)

This measures how many interfaces a class implements. While implementing interfaces supports flexibility and polymorphism, too many interfaces can dilute a class’s identity and increase its obligations. Excessive interface usage may lead to complex dependency graphs and make the class harder to test, understand, or change.

Why to bother measuring?

All these metrics are based on static code analysis. That’s what the tools like SonarQube, Checkmarx, and SwiftLint use to assess code quality. Complexity in software development extends far beyond the code itself—we’ll explore that later. Still, poorly implemented abstract concepts will eventually lead to complex code, which we can measure using these techniques.

There are arguments regarding the origin of this idea, but it doesn’t really matter. Measuring doesn’t necessarily mean controlling, but it’s the first step toward it.

That was it for now, to be continued…

I won’t describe the details of those features, but will share my thoughts on how they change the perception of protocols, and why we can finally say that protocols in Swift are completely different from what they are in Objective-C.

Those changes originated from the discussion initiated by Joe Groff at the forum (back in April 2019 “Improving the UI of generics”) and have been gradually released in 5.x Swift versions. (The initial post was itself a result of previous discussions among the members of the Core team and can be traced back to 2016, the time in between Swift 2 and Swift 3 when Generics Manifesto was created).

The dualism

From the origins of Swift, protocol (as a language feature) was always in between two completely different worlds: compile-time constraints and runtime flexibility.

Runtime polymorphism

From Objective-C protocols inherited their dynamic essence. In this meaning “protocol” is what called “interface” in most of other languages. It’s a capability to define some contract (variables, functions) which then will be implemented by specific data types. So the compiler doesn’t know about a specific type, and exact implementation of the contract is being “attached” only in runtime using dynamic method dispatch. It’s more flexible, but less specific and impossible to optimise by the compiler.

Here is an example of runtime polymorphism:

protocol Animal {}
class Cat: Animal {}
class Dog: Animal {}

var someAnimal: Animal = Cat()
someAnimal = Dog() // we can reassign a value of another type to this variable
var animals: [Animal] = [Cat(), Dog()]

Animal is a specific type both for the variable someAnimal and for the element of the animals collection. Compiler has no idea about the exact types regarding those vars. The exact type doesn’t matter here at all. So protocol behaves like a type itself. This type is called existential type. As you can see variable of existential type can hold values of different concrete types as far as they conform to the protocol. Collection of existentials can be heterogeneous, meaning it can also hold values of different concrete types.

func pat(animal: Animal) {
    // `animal` has a value of existential type `Animal`
}

Compile-time polymorphism

At the same time in Swift world protocol always played a big role in generics. Generics is a system that allows us to specify a set of requirements/constraints that can be later translated by a compiler into specific types. As the types are clear in compile time, the implementations are “connected” to the calls at that stage as well, so static method dispatch is being used. Hence the compiler can help you a lot here during development as well as optimising the code while compiling it.

func pat<T: Animal>(animal: T) {
    // `animal` is a value of some specific type, conforming to `Animal`
}

pat(Dog())
pat(Cat())

Generic type T is being resolved into a specific type for each function call. So we know the exact type (Cat or Dog in this case) inside the pat() function. In this simple example it doesn’t bring us much value, but in a more complex construction it may have a big difference.

Alternative terms

On the Swift forum you may also encounter such terms as type-level and value-level abstraction. They describe the same dualism from the perspective of the compiler.

Generic types (that represent compile-time polymorphism) provide abstraction on a type level so the compiler resolves the abstract types and then can already operate specific types, completely preserving their details (functions, properties). So we have type-level abstraction here.

In case of existentials and runtime polymorphism the exact types covered by protocols are not known for the compiler, so they are replaced by existential types (one protocol - one existential type). So the compiler have only ideas about the existential type and the values that will be assigned to it in runtime. Hence value-level abstraction.

In this forum post you can read more about it.

The paradox

This may not sound like an important thing, but there was a lot of confusion and frustration among the developers regarding the dualism of protocols, up until recently (before the discussed changes were released). Sometimes you were not allowed to use the same protocols in different use cases mixing runtime and compile-time capabilities. In some situation it could also cause some errors and unexpected behaviours (both in runtime and in compilation time). (In our previous articles “Several faces of protocols” and “Do protocols break Single Responsibility Principle?”; we dived into the subject in more details)

There were always different opinions inside the Swift Core Team and most active part of the community regarding Protocols. Some people admitted that there was this feature dualism between the runtime and compile-time capabilities. For instance Dave Abrahams in one of the discussions on the forum said:

I have always thought a big part of our problem is that protocols that are meant to be used for type erasure are fundamentally different from those meant to be used as constraints, yet we declare them the same way.

(The author of this post also belonged to this camp, as you could guess from the previous articles. We even argued that it could have been better to have two separate language features instead of one).

But the majority considered all the capabilities of protocols as one big feature, that temporary had some gaps and contradictions.

Since the first versions, protocols in Swift played more important role as generic types other than existential ones. Runtime polymorphism is less safe, predictable and controllable (as it puts developer in charge, not a compiler), it erases type details, it implies dynamic memory allocation and reference counting, it’s slower and cannot be optimised by compiler. Compile-time capabilities in contrary were more interesting for the swift core team and the community as they are integrated into compiler and interact with other compile-time features.

Existential type is quite a simple language concept, so it wasn’t even widely discussed until recently (not much to talk about). So most public discussions regarding protocols are being held in the context of generics. (There is an opinion that Swift as “Protocol-oriented language” means more “Generics-oriented language”… but it doesn’t sound as fancy).

Existential type is what protocols in Swift inherited from Objective-C as “default behaviour”. You didn’t need any additional syntax to define or return an existential type. In contrary the other features like generic types, when-condition, opaque types require some specific words or constructions. Eventually it started to look paradoxical that major features of protocols related to the generic types require more explicit syntax then secondary feature - existentials. The ideas how to tackle it had been discussed for quite some time before the changes even got to proposal stages.

But first things first…

Filling in the gaps

To consider all the capabilities as one feature some visual gaps should have been fixed.

The biggest gap, as the Core team saw it, was the absence of the ability to return a generic type from a function. Existentials could be used both as parameters and result values. But on a compilation level you could only pass a generic type as a parameter, but were not able to describe the result value. That’s how opaque types appeared (not without SwiftUI playing a noticeable role).

When opaque types were introduced and then expanded to more use cases, the next challenge was to minimize the interference between generic and existential types. Meaning that one shoul be possible to use in case of the other.

The idea of so called generalized existentials was already mentioned in GenericsManifesto. The essence was to make it possible to use generic-type protocols (the ones with associated type or self-constrained) as existential. Another challenge was to turn such existential back to generic when you need it. Some smaller potential improvements were needed for specific use cases. Some of the feature limitations were artificial (kind of legacy), the other required significant changes, but most of the goals were achieved. A number of discussions were held on forum followed by proposals, and eventually several feature changes were released into the language (see References).

As a result, mixing existentials and generic types became seamless. You can create a generic type protocol and use it as existential and vice-versa. The amount of related compilation issues drastically decreased. Now understanding the difference between runtime and compile-time cases is not needed in most of the cases… as it just work.

Completing the paradigm shift

But one “small” change stands out of the list of improvements: explicit existentials (introducing any). It didn’t add any new capabilities.

As time was passing by since the beginning, developers were more and more discouraged to use Existentials. Compile-time capabilities of protocols on the other hand were more and more extended and promoted. They became heavier in functionality and more valuable for the developers. Every other developer, when talking about protocols, kept enumerating the capabilities without even mentioning the original runtime polymorphism. It was just some small feature in the back of their minds, almost a nice side-effect of using protocols.

People in the community (first of all, the Core team) kept questioning the status quo: having existentials as default was considered less and less acceptable. But you cannot just swap the syntax for two different language features, so it was decided to deprecate the default behaviour and create a special syntax for existentials.

That’s why in case of existential declarations (see the code example before) we now should write:

var someAnimal: any Animal = Cat()
var animals: [any Animal] = [Cat(), Dog()]

I’m saying “should” but now it’s a transitive period before the old syntax gets deprecated (expected in the next major language version). So we actually “have to” adopt this new way.

The change makes usage of existentials more explicit. Now it becomes a conscious choice rather than default option. It also eliminates some confusion when mixing existentials with compile-time constrains.

But the most important thing here, imho, is the shift of the protocol paradigm, from legacy Objective-C like runtime interface to a big part of a compile-time abstraction. The shift started when protocols were introduced in Swift, but only now it seem to be completed. From now on protocols will be perceived differently, now there are no doubts that protocols are first of all made for generic or opaque types, associated values, where-conditions and so on, and runtime polymorphism officially takes the second (third, fourth) place.

What can we see in future?

Who knows, maybe eventually the default syntax (defining a value, parameter or result with a protocol without any additional words) will be reassigned back, but this time to the generic/opaque types. That would look like a logical completion of the shift. Possibly in a couple of major releases we will see such syntactic simplification as a new feature in Swift.

The other possible continuation of this story could be compiler warnings that advise you not to use existential when your use case can be covered by a generic/opaque type (Isn’t it already there? Seems logical and easy to implement… but I haven’t heard about it yet).

Even though we might see some other enchancements in this area, as well as further development for the compile-time capabilities of protocols, the shift of the paradigm is completed. Bye-bye dynamic interfaces!

References

Main changes regarding opaque types:

• [SE-0244] Opaque Result Types
  Introducing opaque return types. That’s the feature that was introduced mainly for SwiftUI back in Swift 5.1
• [SE-0328] Structural opaque result types Extending the use cases for the opaque return type. Now it can be a part of another result structure (a tuple or a closure)
• [SE-0341] Opaque Parameter Declarations
  An ability to use opaque types as parameters: more lightweight syntax for parameters with compile-time polymorphism.

Additional changes regarding to opaque types:

• [SE-0346] Lightweight same-type requirements for primary associated types
  An ability to use more precise and complex compile-time parameters with more lightweight syntax.
• [SE-0360] Opaque result types with limited availability
  More future-proof abstraction of opaque types. Now it allows you to return new types as previously declared opaque types. Capability specifically added for making APIs with opaque result types less breakable.

Main changes regarding existential types:

• [SE-0309] Unlock existentials for all protocols
  Now generic type protocols can be used in some cases (still with limitations) as existentials.
• [SE-0335] Introduce existential any
  Making usage of existencial types more explicit.
• [SE-0352] Implicitly Opened Existentials
  An ability to use existential types in some compile-time constrained cases (generics).
• [SE-0353] Constrained Existential Types
  Making it possible to use compile-time constrained protocol as existensials and still keep those constraints (being able to utilize them after)
• [SE-0375] Opening existential arguments to optional parameters
  Allows an argument of (non-optional) existential type to be opened to be passed to an optional parameter.

Key discussions at the forum:

• Improving the UI of generics
• Lifting the “Self or associated type” constraint on existentials
• Improving the UI of generics
• Reverse generics

Other relevant reading:

• Swift Protocols: Magic of Dynamic & Static methods dispatches ✨
• What’s new in Swift 5.6
• What’s new in Swift 5.7
• Using the ‘some’ and ‘any’ keywords to reference generic protocols in Swift 5.7

This post is part of the series on modularity:

• Modularity. Boundaries
• Modularity. Encapsulation
• Modularity. What problem does it solve?

When does the time come?

When is it right time to think about modularization in your project?

It doesn’t look like you should divide your project into the modules from the very creation. You definitely need to follow all the major architectural principles (separation of responsibilities, clear dependencies, architectural layers, DRY, KISS etc.) when building your logic, but you are likely not able to foresee how the project will look like in a year or even several months. Your business ideas, direction of development, target audience, your main features… all may change. At the beginning of its existence, your app can turn into something completely different within several months. So, it doesn’t make sense to start dividing and incapsulating high-level parts of business logic at this point. If you start to design your modules and interactions between them too early, you will be constantly wasting time on restructuring and changing.

The other extremum is when the situation has already gone so far that you need to stop (or at least significantly slow down) development of your features to modularize the project. At this point you might already have more than a dozen of developers, serious commitment to deliver features, ambitious goals… but the project is a mess, technical debt is enormous, bugs are all around and releasing new features gets harder and harder. If you found yourself here, then you should have already modularized your project some time ago. I’m not saying that now it’s already “too late”, no, but it costs you much more troubles to do it now than before.

As always, the truth is somewhere in between, and of course it’s not the same for different teams and different projects.

Making the terms clear

First let’s clarify what we mean when you say that the project is a monolith.

It might have different dependencies, some of them might be your own modules or subprojects. You might already have some separated modules for common data types, or design components, or network layer. You might have several different targets for extensions (watch, Siri, widgets, etc.). BUT more than 50% of your logic belongs to one “main” target (you can roughly count the number of lines of code together with the number of classes/functions). So, you have a monolith.

When we say that the app/project is modular we mean that it consists of a number of modules (separate targets inside one project or one main project and several dependent ones). All the code is spread across those separate logical parts and there are strict physical boundaries between them (read more about the boundaries and different types of projects in our previous article).

Reasons to think about modularization.

Let’s try to figure out some concrete signs of the project that requires modularization. If your project has some of them it’s likely the time to modularize it.

The most popular reason for moving some code to a separate modules is situation when you need to share some logic between several apps. It might be network layer, common data types, functions or UI elements. We omit it here as it’s quite intuitive and doesn’t require much explanation. But there are more than that.

Poor logical separation

At some point your project becomes so big and the flows are so complex that there is not a single developer who understands how all the features work. Plenty of features are not a compilation per se, but quite often those features are poorly separated architecturally. It’s really hard to measure such “architectural health” but if you start asking yourself the following questions you are likely to understand how good/bad the situation is.

• Do you have clear boundaries between the screens, flows and features?
• Do you clearly understand the dependencies of the features?
• How easy it is to use your features/flows in a different context (in a different part of the app)?
• How do you handle shared functions between the features?
• Do you have any incapsulated services for networking, persistence, analytics, logging, error handling… or maybe you put all of these to the extensions (not the best approach)?
• Do you have a lot of data types that don’t really belong to anything?
• Do you use Dependency Injection?
• How many singletons do you have?
• How often do you prefer to use a singleton instead of passing a dependency explicitly? etc.

One of the bad indicators is situations when you try to grasp the context of an unfamiliar feature/service… but you just can’t. It’s not properly separated from the others; you cannot easily figure out all of the dependency. When tracking down the behavior in the debugger you keep on jumping from one place to another between separate classes and even parts of the app.

The more features you have, the more obvious your architectural imperfections are.

A lot of conflicts

Not only conflicts in pull requests matter, but generally how often one developer blocks another in their daily work. Starting from a team of 2 developers you need to somehow synchronize the work and coordinate the effort. With a badly architectured app and some decent number of features it can be painful for just 2 devs to work together. If the health of the code base is better, then even 3-5 developers can work on one monolithic project with a decent (though not the best) efficiency. But the more the team grows the more time on coordination you need to spend. Deliveries never grow proportionally to the size of team (twice more developers are never able to deliver twice more features), but if the amount of deliveries hardly increases when scaling the team that’s a bad sign.

The chances are that you do have some separation of logic and areas of responsibility for developers. Maybe you even have some feature teams dedicated to some specific app parts. But ask yourself how clear the boundaries between them are. How much code reside in the “gray areas” which don’t belong to anything? How often it’s not clear who supposed to work on this or that piece of logic? Or the other way around: there are some parts of the app that are constantly being changed by different developers (because many features/services depend on it).

At some point (sooner than later) constant conflicts and lack of clarity may cause serious frustration in the team (which, as we know, decreases satisfaction level and productivity and can even cost you some team members)

Compilation speed is unbearable

If you have a big monolithic target you need to recompile it entirely after every small change. As far as I understand the compiler still tries to make some smart chooses to decrease the compilation time (more with ObjC code then with Swift), but it doesn’t significantly change the situation. Hence when debugging the code, changing and rebuilding it all the time takes an eternity (can easily reach an hour or two cumulatively during the day). You frequently distract yourself, read articles, browse social media or do something else, so the efficiency drops even lower.

Re-running all the tests

Quite likely if your project is not modularized your test coverage is not so high. Testability and modularization are not strictly connected, but there is a correlation. But let’s imagine that the architectural health is decent in your project, and even if it’s a monolith the code is testable and different parts are logically separated from each other. So, it is possible to have a good test coverage. Let’s keep on dreaming and consider you have it. In this case you need to run all the tests (locally or on CI) for every little change. And as the codebase (and test coverage) get bigger it becomes more and more frustrating (hundreds of UI tests take tens of minutes).

I heard about some smart solutions when people create some functionality clusters and per each change define what part of the tests should be rerun. But in a monolith, it’s just an overkill and waste of resources.

The points above are quite subtle, there are no clear metrics or specific app qualities that you can monitor. It also usually hard to sell it to business to get time for the necessary refactoring. But if you proceed thinking further you can easily see how they affect the main properties of your product.

Decreasing project reliability

It’s a combination of bad architectural separation and code base growth (not talking about general code quality). When you have “spaghetti code” where everything depends on everything it’s hard to change something without breaking something else. You might notice that the number of bugs, crashes and other side effects increases. That quickly influences your users, their satisfaction and opinion about your app (the rating, in-apps or sales inside the app logically go down).

Decreasing efficiency

You spend more time on the maintenance and fixes, more time to synchronize work of different developers, more time on compiling, debugging and testing the code, slow CI pipelines together with high probability of merge conflicts make every merge long and painful, it takes hours and even days to figure out how things work inside an unfamiliar piece of logic… Eventually the development of the new features stalls. If you delivered several features per week/month/sprint before, now this amount noticeably decreased. It’s hard to stick to the planning and meet the deadlines because issues pop here and there all the time.

Maybe you already hear such complaints from the business.

How does modularization help you?

I’m not saying that all the issues will be magically fixed if you modularize your project. Each of the issues above normally has several reasons and all cases are different. You definitely need to also think about using advanced architectural patterns and best practices, apply some code guidelines and QA-tools, check your work processes and the informational channels inside the team. But I’m sure that modularization will help you to improve the situation in all those aspects.

On a high-level, modular project is more structured than the monolith. Module is a separate unit, an extra layer of abstraction. When working on the host app (outside the module) we deal with modules instead of vague “parts” or “layers” that didn’t have clear responsibilities and boundaries. Specific data types on this level become just implementational details, so we can cut these details off. When working inside the module we don’t need to think about the context of the entire app, it doesn’t matter anymore while the module keeps its interface stable. So regardless of your context you decrease the cognitive load by reducing the context.

Modules are independent projects (even when having dependencies from each other) so the scope for the work processes also decreases. We are talking about several small project instead of one big monolith, hence we have independent, much faster development loops (develop, test, release). We have smaller number of features and much less conflicts: now instead of 10 devs working on the same monolith we have 5 teams of 2 devs working each on independent module.

(More details about context separation, and modules as independent projects you can read here)

We don’t have problems with long compilation and lengthy test runs anymore, as all of these is specific to the module. (You still need to debug and test the integration code, but the amount of work decreases several fold).

In big teams (when more than 4-6 devs work on one app) organizational structure normally changes together with the project. Modules work better when they have clear maintainers. So, the next logical step might be to establish some feature teams with clear areas of responsibility.

No-brainer that because all of this the overall productivity and satisfaction increases because generally it just gets easier to work. The prerequisite-consequence connection here is quite straightforward.

Regarding the reliability, reducing both the context and the connections between the parts of the app (and side effects as a result) changes the situation dramatically (in a good way of course =)). Code changes become easier to make and test, issues become easier to localize and debug.

(It was a high level overview of the benefits. In future posts I plan to talk more in details about each one of them: scalability, compilation, work processes etc. mentioning also the challenges that modularisation brings)

Bonus improvements

I already mentioned that there are a number of things that influence the maintainability and reliability of your code that are not directly related to modularization. Some of them are also got improved on the way together with modularization. Some changes are inevitable side effect of the refactoring needed for modularization. Some other improvements just look more logical in a new modular context. The others were just waiting in the backlog for ages and transition to the modular architecture is a good occasion to fix it on the way.

Some examples:

Usage of dependency injection and less singletons will come naturally together with modularization. When you don’t have implicit shared state between the modules you are forced to pass the dependencies explicitly. Inside the modules you can still avoid it and use the dark side of the force (singletons and internal instantiation of dependencies), but you are likely to start questioning this approach as it is not a default approach. If you know all about DI and singletons and just were waiting for the occasion to refactor some legacy shared state (which usually requires quite some changes all around the app), migration to the modules is the time to do it.

You might also rethink some responsibilities in your code (as now you need to draw bold lines between them), on the way you might refactor a couple of god classes the ones that have couple of thousands of lines of code and a bunch of different responsibilities.

Modularity itself and advanced architectural techniques will increase testability of your code.

When designing your modules, you normally would discuss inside the team some general architectural patterns and approaches that your future modules supposed to share. If you go further, you may even write down some guidelines on how the future modules should be created, structured and maintained. That will bring more architectural and/or code style consistency to your code base that increases the productivity even more in future.

You can refactor some small pieces of the legacy ObjC code that just don’t fit your new modular frame of the project.

Of course, you should understand that making several migrations on the same time is not a right thing to do. As well as fixing too much of technical debt simultaneously. So, if you have some small things here and there, go ahead and fix them on the way along with modularization. But if the side fixing of something requires too much additional effort, please put it aside and pick it up later when modularization is over. I know how difficult it can be and how big is the temptation to cure all the diseases at once. I’m sure you will have enough work to do with modularization only, so don’t unnecessary increase the scope even more. All your dirty legacy will be cut into pieces and nicely split into modules together with the rest of your code, so it will be anyway easier to handle it after the modularization.

I hope you liked this piece of reading. If you have any questions, suggestions or corrections you can reach me out on Twitter