Core Design Principles

DRY says every piece of knowledge — a rule, a formula, a fact about the system — should live in exactly one place. So when that rule changes, you edit one spot instead of hunting for copies you might miss.

Ask whether the copies must always change together for the same reason. If yes, it's real duplication — unify it. If they could evolve separately, it's coincidence — leave them. Merging coincidence creates a shared thing that soon needs flags.

The rule of three says wait until you see the same thing a third time before extracting it — two copies aren't enough to reveal what really varies. AHA adds: prefer some duplication over an abstraction you invented too early.

Inside one codebase, sharing costs you a function call. Across services it costs coordination: a shared library of business rules means teams must upgrade and release together. So teams often duplicate small logic on purpose to stay independently deployable.

The same rule often lives in the database schema, the API contract, client code, config files, infrastructure scripts, and the docs. You single-source it by generating the copies from one definition, or by adding automated checks that fail when they disagree.

KISS: choose the simplest solution that works — fewer moving parts, easier to read. YAGNI: don't build a feature or extra flexibility until something actually needs it. KISS shapes how you build; YAGNI decides whether to build now.

Essential complexity comes from the problem itself — real rules, cases and constraints you cannot delete. Accidental complexity comes from how we built it: tooling, layers, workarounds, duplication. Simplifying means removing accidental complexity; essential complexity can only be moved or made explicit.

Building early costs the build itself plus a delay to real work, and if you guessed wrong you carry and repair dead complexity forever. YAGNI fails where changing later is expensive or impossible: published APIs, stored/wire data formats, security models, and hard non-functional requirements.

Speculative generality is machinery built for a future that never arrives — an interface with one implementation, unused parameters, hooks nobody calls. Rule of Three: wait for the third occurrence before abstracting. Until then, duplication is safer than guessing the wrong shared shape.

Buy options, not features: keep code well-factored and tested, defer decisions to the last responsible moment, make data and contracts evolvable (versioned, additive-only, expand/contract migrations), and spend up-front design only on decisions that are hard to reverse.

Separation of Concerns means splitting a system so each part deals with one distinct topic — for example, storing data, applying business rules, or drawing the screen — instead of mixing them all in one place.

They overlap: SRP says one class should have one reason to change, which is SoC applied to a class. SoC is broader — it applies to functions, files, layers and whole systems, including concerns spread across many classes.

Cross-cutting concerns are needs like logging, security checks and transactions that apply almost everywhere. Because they touch every operation, they can't simply live in one module; teams pull them out using wrappers, middleware or framework interceptors instead of copying them into every method.

Layering splits code into presentation, business logic and data access, with dependencies pointing one way. It fails when every small change touches all layers, when layers just pass data through, or when database concerns leak upward. Splitting by feature keeps related code together instead.

Every boundary adds indirection: more files, interfaces and hops to read. If splitting doesn't let the parts change, deploy or be tested independently — and instead makes one change touch many modules — the split costs more than it saves.

Cohesion is how strongly the things inside one module belong together. Coupling is how much one module depends on another. The rule: aim for high cohesion inside modules and low coupling between them.

Worst to best: content (one module touches another's internals), common (shared global data), external (shared external format/device), control (a flag tells the callee what to do), stamp (passing a whole record when only a field is needed), data (passing only the simple values needed). Content and common are worst because a change anywhere breaks everything silently.

From worst to best: coincidental, logical, temporal, procedural, communicational, sequential, functional. Coincidental is a Utils class of unrelated helpers. Functional is a module that does exactly one well-defined job, like calculating sales tax.

Fan-in is how many modules depend on this one; fan-out is how many it depends on. Afferent coupling Ca counts incoming dependencies, efferent Ce counts outgoing. Instability I = Ce/(Ca+Ce) runs 0 (very depended-on, hard to change) to 1 (depends on everything, easy to change). Stable modules should be abstract.

Put boundaries where things change together and are owned by one team; keep what changes together inside one boundary. Accept tighter coupling when the parts share an invariant that must hold immediately, when the domain is still uncertain, or when decoupling would cost more than the change it saves.

Inheritance reuses code by making a new type a subtype of an existing one ("is-a"). Composition reuses code by holding another object as a field and calling it ("has-a"). Prefer composition: it couples types less and can change at runtime.

When a subclass overrides methods, it can depend on how the base class calls its own methods internally. If the base later changes those internal calls — even without changing its public behavior — subclasses silently break. That's the fragile base class problem.

Use inheritance when the subtype is genuinely substitutable for the base everywhere (Liskov), the base was deliberately designed and documented for extension, and both live under one owner. Closed/sealed hierarchies and framework template-method hooks are good fits.

It's a combinatorial subclass explosion: with inheritance you need one class per combination (2×3×2 = 12). Replace each axis with a composed collaborator chosen by interface — a Strategy per axis — so you write 2+3+2 = 7 parts and assemble them.

Delegation means an object forwards calls to a collaborator it holds. You get flexibility, but must write a forwarder per method, and the wrapped object's internal calls dispatch to itself — so your wrapper can't intercept them. That's the self-problem.

Encapsulation means a component keeps its internal data private and exposes only meaningful operations. A getter and setter for every field still lets outsiders read and change all the state, so nothing is actually hidden and no rules are enforced.

Instead of splitting a system into one module per step of the process, split it so each module hides one design decision that is likely to change — a data format, an algorithm, a device, a policy. Everything that would change together lives behind one interface.

Representation exposure is handing out a reference to your internal mutable data. If a method returns the live list, or the constructor stores the caller's list directly, the caller can change that data afterwards without going through your validation, so your rules stop holding.

Publish what callers need to express their intent and what you can promise to keep working; hide anything you expect to change — data layout, algorithms, libraries, protocols. A detail has leaked when a change to it forces callers to change too.

At module or service scale there is no private keyword across process boundaries, so encapsulation must be enforced by explicit published interfaces plus tooling and ownership. A shared database breaks it because every table is effectively a public field any service can read and write.

A design guideline: an object should only call methods on its immediate collaborators, not reach through them into strangers. A "train wreck" is a chain like order.getCustomer().getAddress().getCity().getName() that navigates someone else's object graph.

Method M of object O may call methods on: O itself, O's own fields/components, M's parameters, objects M creates inside itself, and globals in scope. It may not call methods on objects returned by those calls.

Dots don't measure coupling. list.filter(...).map(...).count() has many dots but no new dependencies, while a.getB().doIt() has few dots yet reaches into a stranger. What matters is whether you're walking another object's structure.

Every hidden hop needs a pass-through method, so classes fill with delegating one-liners (the "middle man" smell), APIs get wider, and changes ripple through several files. It's worth paying when the hidden structure is genuinely likely to change.

A long getter chain usually means the caller is pulling data out to do work that belongs elsewhere (Feature Envy). Instead of adding another getter, move the operation into the object that owns the data — tell it what to do.

Instead of reading an object's data and deciding what to do outside it, ask the object to do the job and let it decide using its own data. Behavior stays next to the data it needs.

Both are what ask-style code looks like at scale. Feature envy is one method using another object's data more than its own; anemic model is data-only classes with all logic in services. Fix by moving the logic onto the class that owns the data.

Asking is fine when you only need the value, not a decision about that object: displaying or serializing data, reporting and analytics, test assertions, and pure value objects. The smell is asking and then deciding on the object's behalf.

Have the object report outcomes instead of state: return a result type, emit a domain event, or call a collaborator you can substitute in tests. Assert on behavior and outcomes rather than on fields.

The Law of Demeter limits how far you may navigate - only talk to immediate collaborators. Tell, Don't Ask says who should make a decision. Blindly adding pass-through methods satisfies Demeter's letter while still asking, and bloats the middle object.

CQS says every method should either change state (a command, returning nothing) or return information (a query, changing nothing) — never both. Put differently: asking a question must not change the answer.

Common accepted mixes: stack pop(), queue poll(), iterator next(), compare-and-swap, atomic getAndIncrement, putIfAbsent, and getOrCreate. Each needs the read and write to happen as one atomic step, which two separate calls cannot guarantee.

CQS is a method-level style rule: a method either mutates or returns, never both. CQRS is an architecture pattern: separate read and write models — often separate objects, services, or even databases — for the whole system or a bounded context.

If queries have no side effects, a call can be replaced by its result without changing the program — that is referential transparency. It lets you cache, reorder, parallelize, retry, and safely inspect calls in logs and debuggers.

Enforce it with conventions the tools can check: naming, return types (commands return nothing or just an outcome), separate command/query interfaces, and lint or architecture tests. On HTTP, map queries to safe methods like GET and commands to POST/PUT/DELETE.

Abstraction hides detail behind a simpler idea you can reason about, like 'send a payment'. Indirection just means going through something in between instead of calling the thing directly. Abstractions use indirection, but a pass-through wrapper that hides nothing is only indirection.

A leaky abstraction is one whose hidden details still show through — usually as performance surprises or unusual errors — so you must understand what is underneath to use it correctly. The law says all non-trivial abstractions leak to some degree.

Each layer adds code to read, a jump when tracing a bug, another place behaviour can differ, and sometimes runtime cost. A layer earns its place when it hides real complexity or enables a change you actually need now — not a hypothetical one.

Extract when the pieces are the same idea, not merely the same text, and when they change together for the same reason. If they only look alike, keep the duplication — a shared abstraction forced to serve two different reasons grows flags and branches and becomes harder to remove than the copies were.

A deep module offers a small, simple interface but hides a lot of work; a shallow one exposes almost as much complexity as it contains. Prefer fewer, deeper boundaries — each interface is a cost paid by every caller.

It says a component should behave the way a reasonable reader expects from its name and the surrounding conventions. If people are surprised by what a function does, the design is wrong even when the code is correct. Names must promise exactly what happens.

A hidden side effect is a change (write, send, mutate) that the caller cannot see from the call. It breaks the reader's mental model and causes bugs that only appear at runtime. Command-Query Separation says a method either returns data or changes state — never both.

It means failures are reported the same way everywhere, so callers can predict what happens without reading each implementation: one style of signalling errors, consistent handling of "not found" versus "invalid" versus "broken", and a clearly defined state after a failure.

Defaults are what most people actually get, so they must match the common case and never hide risk. Pick the value an informed user would have chosen; when the expected default is dangerous — no timeout, verification off — choose the safe one and make the risky option explicit.

Ask whose expectations you are breaking, how often they will hit it, and how bad it is if they guess wrong. Break an expectation only when the gain is large and durable, then make the surprise loud and impossible to miss — in names, types, and tooling.

Fail fast means checking for invalid input or state right where it appears and stopping immediately with a clear error, instead of continuing with bad data that causes a confusing failure much later somewhere else.

If an object checks its rules when it is created, an invalid one can never exist, so no later code has to re-check or handle it. Validating later means broken objects float around until something notices.

Fail fast when continuing would give wrong answers or corrupt data. Degrade instead when the failure only affects a non-essential part and the core result is still correct - for example hiding a recommendations panel rather than failing the whole page.

Assertions check assumptions the developer believes are always true and are often switched off in production. Guards check what a caller must supply and always run. Input validation checks data from outside and produces a user-facing error. A security check written as an assertion can vanish in production.

Best is catching it when the code is compiled or built, then in CI, then when the service starts, then on the first request, and worst is never noticing. The earlier the catch, the fewer people are affected and the cheaper the fix.

Every fact — a piece of data, a setting, a rule — lives in exactly one authoritative place. Everything else reads from that place or is generated from it, so copies can never quietly disagree.

DRY is about not duplicating knowledge in code; SSoT generalises the same idea to data, config, schemas and docs. Database normalization is the data-modelling technique that implements SSoT: each fact stored in exactly one place.

Make every copy generated, never hand-edited; give each one a defined refresh mechanism (regeneration, invalidation, replication, or an event stream); make regeneration cheap and repeatable; and add a check that compares copy against owner and alerts on mismatch.

Keep one machine-readable schema file as the definition, generate server stubs, client code, validation and docs from it, never hand-edit the generated output, and have CI regenerate and fail the build if the result differs from what is committed.

Give each fact to exactly one service — the one that owns the business rules for changing it. Others read it or subscribe to its change events; they never write it. Two writers means conflicting values with no rule for which is correct.