Design by Principles

Chapter Info

Calculating... Writing Progress: 80%

Software design is not about following rigid rules or memorizing patterns. It is about understanding the forces at play and making deliberate trade-offs. At its heart, design is the battle against complexity accumulation: keeping systems understandable, adaptable, and useful as they grow.

This chapter explores design in two parts. First, the human side: the mindset that shapes how we think, the reality constraints we must navigate, and the practical habits that prevent unnecessary complexity. Then, the structural side: the foundational principles — Separation of Concerns, Single Responsibility, Open-Closed, Dependency Inversion — and other principles that guide technical decisions. Whether you're designing a new system or evolving an existing one, these principles serve as a compass—not a prescription—helping you navigate the complex landscape where technical excellence meets organizational reality.

Design Mindset [Design Mindset] {1}

The Big Ball of Mud: The Default [Big Ball of Mud] {1}

The most common architecture in the world is no architecture. Foote and Yoder gave it a name — the Big Ball of Mud — precisely because it is the default outcome of building software without deliberate design: code accretes without boundaries, every part touches every other part, and after a few years no one remembers why anything is where it is. !!It is not the result of bad intentions; it is the result of no decisions!!. Every principle in this chapter exists for one reason — to push back against this silent gravity.

What is Software Design? [What is Design] {1}

Software design is the art of solving real-world problems through systems that must evolve over time. Requirements shift, technologies evolve, user needs grow — the challenge is not just building something that works today, but creating systems that can adapt tomorrow without collapsing under their own complexity.

The enemy is !!complexity accumulation!!. Every feature added, every shortcut taken, every "temporary fix" that becomes permanent adds weight to the system. What once took hours now takes weeks. What was once clear becomes opaque. What was once flexible becomes rigid.

Source: Clean Architecture: A Craftsman's Guide to Software Structure and Design

The Only Way to Go Fast Is to Go Well [Go Fast Well] {1}

In his seminal book Clean Architecture: A Craftsman's Guide to Software Structure and Design, Robert C. Martin states that "The only way to go fast is to go well" is one of the core principles of sustainable software development. In the long run, speed and quality are not opposing forces. Clean, well-structured code is what allows teams to keep moving quickly over time. Poor design may create the illusion of speed at the beginning, but it eventually turns every change into a negotiation with technical debt.

Design Is Everywhere — And Everyone's Business [Design is Everywhere] {1}

Design is not limited to UI screens or architecture diagrams. It appears in every decision across the software lifecycle: naming a variable, structuring a function, defining a deployment path, shaping logs, or choosing infrastructure. !!And design is not only the architect's job!! — developers, testers, DevOps engineers, product managers, and platform teams all influence the system through their choices, and every one of those choices leaves a mark on readability, maintainability, reliability, and long-term adaptability.

Design Without Borders [Design Without Borders] {1}

Most design happens under a narrow lens: a single ticket, a single sprint, a single team. The decision looks reasonable inside that frame — and that is exactly the trap of !!micro-design!!. A function that fits this story but breaks the module. A service that solves this team's problem but fragments the platform. A shortcut that ships this week and shapes the codebase for years. !!Each choice is locally optimal, globally incoherent!!. Good design steps back from the ticket and asks the higher-level question: why are we doing this, and what does it mean for the parts of the system I am not looking at right now? The whole graph matters — because coupling, latency, and complexity cross every line on the org chart, whether the designer chose to look or not.

Design Starts at Time Zero [Design Time Zero] {1}

Security, observability, testability, and performance are not features you add later — they are properties you design in from the start. A system that was never designed to be observable cannot easily be made observable after the fact. A system that was never designed to be tested will resist every attempt to retrofit tests. The same applies to security, scalability, and resilience. Time zero is the moment of design. Every decision made then — how components communicate, where state lives, how failures are handled — shapes what the system can become. Treating these qualities as afterthoughts is one of the most common and costly mistakes in software development.

The Quest for Simplicity: Foundation of All Principles [Simplicity] {1}

Software design is guided by many principles — modularity, testability, security, scalability, resilience. Each one matters. But !!one principle sits above all others: simplicity!!. Without simplicity, every other principle becomes harder to achieve. A complex system resists testing. A complex architecture hides security flaws. Complex code slows scalability. Simplicity is not just one principle among many — it is the foundation that makes all others possible. It is what allows a system to remain understandable, changeable, and trustworthy over time.

Learn More

Chapter: Design for Simplicity.

Make the System Smart So Consumers Don't Have to Be [System Smart] {1}

A well-designed system !!absorbs complexity so its consumers don't have to face it!!. Whether the consumer is an end user, another developer calling your API, an operator running your service, or a team building on top of your library, the principle is the same: every concern the system can hide is one less burden on the people who depend on it. Sensible defaults, forgiving inputs, automatic recovery, clear error messages, hidden edge cases — these are deliberate design decisions, not nice-to-haves. The opposite path — pushing configuration, edge cases, and recovery up to the consumer — is the easiest road for the implementer and the most expensive road for everyone who comes after.

Design is a Journey [Design as a Journey] {1}

Design is not a one-time act—it is a continuous, iterative process shaped by dialogue, feedback, and confrontation with reality. Unlike a destination you can reach and declare complete, design is an ongoing journey that never truly ends. Each decision opens new paths, each solution reveals new challenges, and each implementation teaches new lessons. Good design evolves through trial and error, conversations with stakeholders, and the tension between conflicting needs. The first version is rarely the best—it's simply the starting point.

Revisit Decisions When Reality Changes [Revisit Decisions] {1}

A design decision that was right on day one may not be right on day five hundred. !!Decisions are not permanent truths — they are responses to a context that itself evolves!!: requirements, scale, team maturity, technology, business priorities. A monolith may be the right choice when a product is young and speed matters most; the same monolith may become a bottleneck when the organization grows and teams multiply. The original decision was not wrong — reality simply moved. Mature teams revisit their architecture deliberately, through small and safe changes, instead of waiting for the moment when a painful rewrite becomes the only option.

Model the Business [Model the Business] {1}

A system should be built around the concepts of the business it serves — customers, orders, transfers, accounts — not around technical abstractions invented for the developer's convenience. Recording a financial transfer and recording a user login may look identical at the code level — both write a row, both return a status — yet the business meaning is completely different: one demands auditability, strong consistency, and strict authorization; the other tolerates much simpler guarantees. !!When code and business share the same vocabulary, the system becomes easier to discuss, easier to evolve, and far less likely to drift away from what it is supposed to do!!. This is the core idea behind Domain-Driven Design (DDD): the architecture is shaped by the domain, not by the database schema or the framework.

Focus Design Where It Matters [Strategic Design Investment]

Not all parts of a system deserve the same design investment. Stable areas should remain simple. Volatile areas — business rules, integrations, scaling points, user workflows — deserve stronger boundaries, abstractions, and tests. Good design is not about making everything flexible. It is about identifying where change is likely and protecting those areas from becoming expensive to modify. Over-designing stable parts creates unnecessary complexity; under-designing volatile parts creates future pain.

Design effort should follow expected change.

Understand Before You Deviate [Conscious Deviation]

Best practices encode hard-won lessons from past failures — but they are guidelines, not laws. What matters is how you deviate. Conscious deviation means you understand why the pattern exists, evaluated the trade-offs, and decided it doesn't fit your context — this should be documented. Ignorant deviation means you don't know the pattern exists at all — and you end up rediscovering problems others already solved. RFC 2119 captures this in its definition of SHOULD: "the full implications must be understood and carefully weighed before choosing a different course." The goal is neither blind conformity nor reckless innovation — just informed decision-making.

Design in Reality [Design in Reality]

Bridging Reality and the Ideal [Reality Bridge]

Design lives between two worlds: the ideal world of principles and the physical world where systems run, users behave unpredictably, budgets are limited, and legacy exists. !!Good design keeps one foot in each world!! — reaching toward clarity and long-term elegance, but staying connected to what can actually be built, operated, and maintained. And reality itself is contextual: a startup's reality is not an enterprise's reality — so design for the world you're actually in, not the one described in blog posts from companies at a completely different scale.

Solve Problems at the Source, Not the Symptoms [Fix the Real Problem] {1}

Mature design distinguishes symptoms from causes. Addressing only what is visible or urgent produces superficial fixes that bring momentary relief while the underlying issue keeps growing. Each workaround adds friction and hides the real problem deeper. True simplicity comes from intervening where the cause lives, not where the pain appears — repeatedly asking why, challenging assumptions, resisting the comfort of the quick fix.

Addressing Root Causes Requires Courage [Courage to Fix Root Causes]

Solving problems at the source is rarely easy. The root cause may sit outside your team, challenge an established practice, or require convincing people who do not feel the pain directly. It is often easier to patch the symptom and move on. This is why root-cause design requires courage. It means resisting the small fix when the real problem is bigger, and accepting the discomfort of addressing the source before it compounds into something harder to change.

Design is About Making the Right Decision [Right Decision] {1}

There is no perfect design in absolute terms. There are only decisions that fit a specific context and set of priorities. Every design is a trade-off: performance vs. simplicity, flexibility vs. speed, scalability vs. cost. Good design communication makes these trade-offs visible. When presenting a proposal, do not drown people in every possible option. Curate two or three meaningful alternatives, explain their consequences, and help the team choose deliberately.

The Ripple Effect [Ripple Effect] {1}

At the system level, a single design decision cascades like a ripple on a pond. A seemingly minor choice in code structure today can reshape performance tomorrow; a quick fix in one service can quietly compromise scalability across the whole system; a slightly inefficient query may only reveal its impact under load; a hastily designed API may limit future integrations for years. Every decision — from variable naming to schema design, from a multi-tenancy model to a database choice — carries weight beyond its immediate context, because software systems are interconnected ecosystems where microscopic choices trigger macroscopic effects.

Every Decision Writes Company DNA [Decisions Become DNA]

The ripple effect doesn't stop at the system — it shapes the organization itself. No single decision writes a company's DNA, but their accumulation does. When inconsistencies, shortcuts, and badly-made choices pile up across years and teams, they stop being individual mistakes and become the organization's identity: the way the company builds, the things it can no longer change, the constraints every future team inherits without ever choosing them. A company's DNA is not declared in a strategy document — it is written, one quiet decision at a time, by the cumulative weight of everything that was ever shipped.

Design Practices [Design Practices] {1}

Knowing how to think about design is not enough — you also need habits that keep complexity from creeping in. These practices are concrete rules of action: things to do (or avoid) daily that prevent systems from deteriorating over time.

Vision Sets the Direction [Vision Sets Direction] {1}

Vision is what gives a system a direction. !!It is the long horizon a system is moving toward — and direction is the shape of every step taken in its name!!. With a vision, isolated decisions align: every change becomes a small bet on a future the team has agreed to build, and over time those bets compound into architecture. Without it, the same decisions are only locally reasonable — globally incoherent — and the system erodes by accumulation, one well-meaning increment at a time. Vision is what turns isolated decisions into a coherent system. It is the difference between motion and direction.

Plan First [Plan First] {1}

A plan written before the first line of code is what separates engineering from improvisation. !!Long before AI, planning first — sketching the design, drafting the contract, breaking the problem into steps — was what kept teams from building the wrong thing fast!!. With AI, the principle deepens for a mechanical reason: !!LLMs generate one token at a time, each token committing to the next, so an unplanned start locks the model into a local minimum it cannot escape!!. The wrong solution arrives fully written and internally coherent — confident, fluent, and off-target. Whether the typing is done by a human or a machine, thinking before building is what makes the result worth keeping.

Document the Why, Not Just the What [Document the Why] {1}

!!Code shows what the system does. Documentation shows why!!. Without the why, future teams are forced to guess from the code alone — and they will guess wrong, because code rarely encodes the constraints, assumptions, and trade-offs that shaped it. Good documentation is not bureaucracy, it is memory. An ADR only needs to capture the context, the decision, the alternatives rejected, and the consequences accepted.

Preserve the Prompt, Not Just the Code [Preserve the Prompt] {1}

When code is generated by an LLM, !!the prompt is the why!!. It captures the constraints the developer expressed, the trade-offs they chose, the alternatives they implicitly rejected — none of which survive in the generated code itself. Reading the code, a future engineer might wonder: "why was it written this way and not the obvious alternative?" The answer often lives only in the prompt: a deliberate bias the developer introduced. Preserving prompts alongside the code is the modern continuation of the ADR — same purpose, new medium.

Stop Adding Your Own Complexity [Complexity Types] {1}

Some complexity is built into the problem itself — we can't avoid it. But we often add our own complexity on top through bad choices. Built-in complexity is what the problem naturally requires; self-inflicted complexity is the mess we create ourselves with poor tools, confusing code, or overcomplicated processes. !!Recognizing which is which is what lets teams clean up their own mess instead of blaming the problem!!.

YAGNI – Avoid Over-Engineering [YAGNI Principle] {1}

"You Aren't Gonna Need It" (YAGNI) reminds us not to build features or systems before they are necessary. Over-engineering adds unnecessary maintenance and complexity without guaranteed value. Build for what's needed today, and design with enough flexibility to adapt tomorrow.

Walk Before You Run [Walk Before You Run]

!!Earn each level of sophistication before climbing to the next!!. Before designing for multi-cloud, master a single cloud. Before optimizing for millions of users, make it work for thousands. Before building abstractions that span multiple contexts, prove value in one. The principle is not about lack of ambition — it is about earning your complexity: each level should be justified by an actual constraint you are facing, not by a hypothetical future. Teams that rush to advanced patterns without mastering the fundamentals accumulate complexity they have no experience managing.

Thin is Healthy [Thin is Healthy] {1}

The most successful systems are thin—they do less but do it exceptionally well. Thin design focuses on what is essential, keeping simplicity and clarity at its core. Every extra feature or abstraction adds cognitive load, maintenance cost, and points of potential failure. Thin systems are easier to understand, faster to adopt, and simpler to maintain. They avoid the temptation to solve every problem, instead solving the right ones with precision. When systems grow thick, they often lose elegance and become harder to evolve. The goal is not to build everything, but to build what truly matters. Thin is healthy—sustainable, maintainable, and aligned with long-term simplicity.

Don't Optimize What Shouldn't Exist [Eliminate Before Optimize]

The fastest, cleanest code is the code you never need to write—or keep. Before tuning queries, parallelizing pipelines, or shaving milliseconds, first ask whether the feature, workflow, or even the system is necessary at all. Optimization entrenches waste by making it feel valuable and harder to remove later. Good design deletes, simplifies, and merges until only the essential remains; then, and only then, optimize what demonstrably matters. Every optimization carries maintenance cost, cognitive load, and lock‑in. Eliminate and clarify first; optimize only after necessity is proven by real usage and measurable value.

"We Can Clean It Up Later" is a Fallacy [Cleanup Fallacy]

"We can clean it up later" rarely happens. Market pressure does not subside, the urgency to ship only grows, and technical debt compounds faster than any team's promise to itself. Each shortcut makes the next change harder, until the system is so expensive to modify that "later" is permanently delayed. !!The only reliable cleanup is the one that does not need to happen!! — clean design from the start.

Design by Easy Choices [Easy Choices] {1}

Developers naturally gravitate toward what looks easiest in the moment — directly coupling components rather than defining interfaces, patching rather than refactoring, reusing another team's database rather than asking for an API. Each choice looks reasonable on its own; together they accumulate into the kind of complexity that makes everything harder later. !!True simplicity is not what feels easy today — it is what stays easy tomorrow!!.

Continuous Refactoring Shapes Sustainable Systems [Continuous Refactoring] {1}

Refactoring is not an occasional cleanup task; it is how design quality survives. A healthy codebase evolves through small, continuous improvements that keep complexity manageable and prevent technical debt from hardening. Waiting for a future refactoring sprint rarely works. Refactoring should be part of normal development: when a feature is done, the code should not only work, but remain understandable, testable, and safe to change.

SOLID Principles [SOLID Principles]

SOLID gathers the four foundational principles every well-designed system rests on: Separating Concerns (split a system by responsibility), One Owner per Component (each piece has a single reason to change), Extending Without Breaking (grow by adding, not by editing), and Depending on Abstractions (business logic must never be tied to implementation details). Together they form the structural backbone of maintainable software — each one independently useful, all four reinforcing each other.

Separating Concerns (SoC) [Concerns]

Separation of Concerns (SoC) [Separation of Concerns]

A system is easier to understand, change, and trust when each part handles one thing. !!Separation of Concerns is the first line of defense against the Big Ball of Mud!!: instead of letting a single piece of code juggle the user interface, the business rules, and the storage at once, SoC carves the system into units that each own a clear, narrow purpose. The payoff is concrete — you can change one concern without disturbing the others, you can test in isolation, and a new developer can read one unit without having to load the entire system in their head.

SoC at Every Scale [Every Scale]

Separation of Concerns is not something you do once at the architecture level — it is a reflex that should accompany a developer throughout the day, at every scale of decision. One line should do one thing. One function should express one verb. One class should own one role. One module should cover one domain. One service should serve one bounded context. From the first variable named in the morning to the last service deployed at night, the same question keeps coming back: "is this unit doing one thing?"

Cohesion: The Other Half [Cohesion]

Separating is only useful if what stays together belongs together. Cohesion is the silent partner of SoC: each separated unit must itself be tightly focused around a single purpose. Without cohesion, you do not get clean modules — you get a pile of fragments, each as confused as the original system, just smaller. !!The classic formulation captures both halves at once: high cohesion within, low coupling between!!. SoC fails the moment you optimize one without the other.

Boundaries Need Contracts [Boundaries Need Contracts] {1}

Separating concerns draws a line between two units — but a line alone is not a frontier. !!Without a contract, separation is just an illusion!!: the units keep talking through implicit assumptions, shared formats nobody wrote down, and constant coordination meetings to figure out what the other side really expects. A contract turns the line into a real boundary: each side knows exactly what it must deliver and what it can rely on, and both sides become autonomous — free to evolve internally as long as the contract holds. SoC creates the separation; the contract is what makes the separation hold.

One Owner per Component (SRP) [Owner]

Ownership Defines Architecture [Ownership Clarity]

When components lack clear ownership, responsibilities blur. Different teams make conflicting changes, features land wherever convenient rather than where they belong, and the codebase becomes entangled — hard to understand, test, or modify with confidence. Well-defined ownership fixes this. It forces teams to think deliberately about where new functionality should reside, clarifies accountability, and keeps decision-making fast. Every module or service should have a single, dedicated owner.

Every Component Should Have Only One Owner: Single Responsibility Principle (SRP) [SRP]

In a well-designed system, each component should have only one "Owner"—a single, clear reason to change. This is known as the Single Responsibility Principle (SRP)

When multiple stakeholders, such as HR, Accounting, and Database Administration, influence a component, conflicting requirements create complexity, making the system harder to maintain and modify. For example, if a module handles payroll processing (Accounting), employee records (HR), and data storage (Database), a change requested by one group might unintentionally disrupt another, creating unnecessary dependencies and increasing maintenance costs.

By ensuring that each component has one well-defined responsibility, we create a modular, predictable, and adaptable system. This approach reduces unexpected side effects, simplifies debugging, and makes the system more scalable and maintainable over time.

Reducing Dependencies [SRP Dependencies]

By constraining components, services, classes, or modules to have only one owner, we promote a clear and structured architecture. When each part of the system is responsible for a single concern, it becomes easier to understand what needs to change and why, reducing the risk of cascading failures. Without this structure, systems become tangled—where multiple elements depend on each other in ways that make even small changes risky and time-consuming. Instead of a spaghetti-like web of dependencies, SRP encourages a clean, loosely coupled design, where changes remain localized, and the system can evolve with minimal disruption.

Source: Clean Architecture: A Craftsman's Guide to Software Structure and Design

Extending Without Breaking (OCP) [Extending]

Open-Closed Principle (OCP) [OCP]

Software should be designed so new functionality can be added without altering existing code. The Open-Closed Principle (OCP) captures this directly: a class, module, or component should be open for extension (new behaviors can be added) but closed for modification (existing code stays untouched). A well-designed structure — like a building — allows new floors or rooms to be added without tearing down what already works.

OCP in Code [OCP in Code]

In code, the mechanism is abstraction: well-defined interfaces, inheritance, or composition. Introducing new behavior means writing a new module, not rewriting the old one. In a reporting system, adding a new export format (CSV, PDF, XML) should mean adding a new export class — not editing the core with another if format_type == ... branch. This keeps regression risks low, preserves backward compatibility, and lets the system grow without becoming brittle.

Self-Describing Extensions [Self Describing]

When systems grow through plugins or adapters, a common mistake is to stash every extension's rules—permissions, concurrency, contracts, presentation—in one coordinator. That hub becomes a god object: each new extension forces edits to shared code and risks regressions far from the change. Better: keep each extension self-describing so the core does not need to know every name in the catalog.

The framework should offer generic mechanisms—discovery, schema validation, policy enforcement—not a growing list of special cases. A thin registry for wiring is fine; embedding extension-specific logic in the center is not. This extends the Open-Closed idea: new behavior ships mostly in the new module, not in an omniscient orchestrator.

Depending on Abstractions (DIP) [Abstractions]

Decoupling Implementation Details [Decouple Details]

Business logic should be defined at the highest level of abstraction, focusing on what needs to be done, rather than how it is implemented. To ensure flexibility and maintainability, implementation details should remain hidden from the core business logic.

Dependency Inversion Principle (DIP) [DIP]

This principle is called the Dependency Inversion Principle (DIP) because it reverses the control of dependencies. Before applying DIP, high-level business logic was directly coupled to low-level modules that it did not control. This created rigid dependencies, making it difficult to modify or replace implementations.

With DIP, the high-level module defines the contract (interface), and the low-level module must conform to it. Instead of business logic depending on specific implementations, both high- and low-level modules depend on a shared abstraction.

Code Against Contracts, Not Concretes [Code Against Contracts]

Business logic acts as an orchestrator, coordinating operations that depend on external services — databases, payment systems, notifications. The rule is simple: in business code, never name a concrete implementation. Talk to a contract instead — PaymentInterface, StockInterface, NotificationInterface — so any compatible implementation can be plugged in without changing the orchestration.

From Implementation to Abstraction [From Implementation to Abstraction]

The shift is small in code but huge in architecture. Before DIP, OrderService is tightly coupled to NotificationEmailService — change the email vendor, change the order code. After DIP, both OrderService and NotificationEmailService depend on the same abstract contract: the high-level no longer points at the low-level, they both point at the interface in the middle.

Dependency Injection at Runtime [Dependency Injection]

Once business logic depends only on abstractions, someone still has to provide the real implementation. That responsibility moves outside the business logic — to a dependency injection container, a framework, or a wiring layer. At runtime, this external mechanism creates the concrete services and injects them into the orchestrator. The business logic stays clean; the plumbing lives elsewhere.

If You Can Replace It, It's a Detail [Replaceable Detail]

In a great orchestra, each musician can be replaced — what truly matters is the melody. Software is the same: anything you can swap without rewriting the business rules is, by definition, a detail. The database, the framework, the queue, the protocol — they are interchangeable instruments. The melody is the architecture.

Core vs Details [Core vs Details]

Most teams get the priorities backwards. They start every project by picking the database, the framework, the cloud provider — and only then write the business rules around them. But those choices are details. The core is the part that cannot be replaced without changing what the product does: business rules, domain logic, data model. Everything else conforms to the core, never the reverse.

Do Not Let Details Drive Architectural Decisions [Details vs. Architecture]

The clearest sign that DIP is being violated is when implementation details leak directly into the architecture: a raw SQL query in business code, a framework annotation in a domain rule, a vendor SDK class in a core service. Technologies are tools, not pillars — when they dictate the architecture, the system becomes rigid, brittle, and tied to choices that will outlive their relevance. Good design pushes details to the edge and keeps the core clean.

Twisting a Good Design to Fit New Details [Design Twist]

When new technical requirements or constraints emerge, there's often pressure to modify a well-designed architecture to accommodate them. This "twisting" of good design to fit new details is a dangerous practice that compromises architectural integrity. Instead of adapting the design to fit the details, the better approach is to evaluate whether the new details are truly necessary, find alternative solutions that don't require architectural changes, or refactor the design properly to accommodate the new requirements. Twisting a design often leads to technical debt, increased complexity, and systems that become harder to maintain and extend. The key is to resist the temptation of quick fixes and instead invest in proper architectural solutions that maintain design quality while meeting new requirements.

If You Can Replace Details Easily, You Can Test It Easily Too [Testability]

A well-designed system allows implementation details to be replaced easily, making testing more effective and maintainable. By using mocks and stubs, we can isolate business logic from low-level dependencies, ensuring that tests focus on validating rules rather than technical details. This approach leads to stable tests that remain valid even if the database, framework, or API changes. When tests are tightly coupled to implementation details, they become fragile and require constant updates, defeating their purpose. Instead, designing for replaceability ensures that tests remain resilient, fast, and focused on verifying the core functionality rather than the underlying mechanisms.