Design Principles Course

Welcome to Design Principles: From Clean Code to Staff Engineering Excellence — an internal academy for engineers who need maintainable systems, principled code reviews, archite…

Design principles are durable guidelines for structuring code and systems — they describe forces and trade-offs (cohesion, coupling, change isolation) rather than specific reusa…

Principles state enduring forces; patterns are named, reusable solutions to recurring problems.

Rules are enforceable constraints (lint, CI, style guides).

Principles matter most when change cost exceeds abstraction cost — typically after the second use case, when multiple teams touch the same module, or when incidents correlate wi…

Code quality is a business investment — not aesthetics.

Common myths — "SOLID always," "more interfaces = better," "DRY means no duplicate lines" — cause over-engineering.

SOLID — five principles from Robert C.

SRP — a module should have one reason to change: one actor or axis of change drives modifications, not "one method only" literalism.

OCP — software entities should be open for extension (new behavior) but closed for modification (existing tested code stays stable).

LSP — subtypes must be substitutable for their base types without breaking client expectations.

ISP — clients should not depend on methods they don't use.

DIP — high-level modules should not depend on low-level details; both depend on abstractions.

SOLID in practice means applying letters together with trade-offs — not maximizing interfaces.

DRY (Don't Repeat Yourself) — every piece of knowledge should have a single, authoritative representation.

KISS — prefer the simplest design that meets requirements.

YAGNI — don't build capability for hypothetical futures.

SoC — distinct sections of a program should address distinct concerns with minimal overlap.

LoD — a module should not know the internal details of objects it manipulates.

Favor composing behaviors over deep inheritance trees — avoids fragile base class and LSP violations.

Depend on abstractions (interfaces, protocols) not concrete classes — enables substitution and testing.

Code should behave as readers expect — surprise causes bugs and review friction.

High cohesion, low coupling — modules do related work together and depend minimally through stable interfaces.

Prefer immutable data structures where practical — reduces shared mutable state bugs and simplifies reasoning in concurrent systems.

Detect and report errors at the earliest point — don't propagate invalid state.

Validate inputs and invariants at boundaries — balance with fail-fast clarity, not silent swallowing.

Tell objects what to do rather than querying state and deciding externally — keeps behavior encapsulated.

Hide implementation details behind stable interfaces — Parnas's foundational idea behind encapsulation.

Encapsulation bundles data and behavior, controlling access — not merely private fields.

Pure functions same output for same input, no side effects — easier to test and parallelize.

Depend in the direction of stability — volatile modules depend on stable ones, not vice versa.

Package dependency graph must be acyclic — cycles prevent build ordering and clear ownership.

Classes that change together should be packaged together — reduces release friction.

Don't force clients to depend on things they don't use — package granularity matters.

Abstractions should be more stable than implementations they abstract.

Orthogonal components change independently — change in one does not affect others (Pragmatic Programmer).

LoB — behavior should live near the code it relates to; balance with DRY at the right level.

Managing third-party and internal dependencies — semver, pinning, and abstraction at boundaries.

Daily application — principles in every PR, standup refactor note, and tech debt ticket — not a quarterly architecture initiative.

Principled code review — comment with smell + principle + suggested refactor — never vague "clean this up."

Legacy code (Feathers: code without tests) — apply principles incrementally with characterization tests and seams.

Capstone — refactor UserAccountFacade (900 lines, 12 responsibilities) with SRP, DIP, OCP, DRY incrementally.

Interview framework — read code, name violations, propose minimal refactor, state trade-offs, connect to tests — in 35 minutes.

Mock SOLID review — practice reviewing a realistic PR with SRP, OCP, LSP, ISP, DIP violations.

Trade-off mock — when SOLID conflicts with KISS/YAGNI, articulate the decision framework.

Cheat sheet — quick reference for reviews and interviews.

Idempotent handlers produce the same outcome when executed multiple times — essential for at-least-once delivery in distributed systems.

Accept eventual consistency only at explicit boundaries with compensating actions and clear user-facing semantics.

Long-running distributed transactions use sagas — orchestrated or choreographed steps with compensating transactions.

Publish domain events at bounded context boundaries — consumers depend on event contracts, not internal models.

Stable API contracts — versioning, backward compatibility, and consumer-driven contracts at service boundaries.

Fail fast when dependencies are unhealthy — bulkheads and circuit breakers prevent cascade (Release It!, Nygard).

CAP — partition tolerance is mandatory; choose consistency vs availability per use case, not globally.

Decompose by bounded context and change isolation — not by technical layer alone.

Stripe API design embodies ISP, idempotency, and stable abstractions — developer experience as architecture principle.

Netflix — freedom and responsibility — principles in microservices, chaos engineering, and paved-road platforms.

Google readability — principle-based review culture scaling to millions of LOC across languages.

Amazon — two-pizza teams, service-oriented architecture, and working backwards from PR/FAQ — organizational principles driving technical boundaries.

Spotify squads — autonomy with alignment — principles for squad boundaries, guilds, and shared infrastructure.

Formal architecture review — who attends, artifacts required, outcomes, and escalation paths.

Come prepared: context, options considered, trade-offs, SLO impact, rollback — not slide-deck theater.

Architecture Decision Records — context, decision, consequences, status — Michael Nygard format.

Staff engineers facilitate — draw out dissent, timebox, ensure decision owner, capture action items.

Score designs against principles: coupling, testability, operability — not checklist patterns.

Reviews that fail: no decision owner, bikeshedding, architecture astronautics, missing rollback.

Gradually replace legacy by routing traffic to new system at seams — Fowler's strangler fig.

Tests that capture current behavior before refactor — Feathers' legacy code lifeline.

Find points where behavior can change without editing call sites — object seam, preprocessing seam.

Extract one responsibility per PR — trunk-based development with principles.

Introduce interfaces at boundaries already touched by changes — don't boil the ocean.

Decompose by bounded context and business capability — identify natural seams.

Every migration slice needs rollback — feature flags, dual-write parity, reconciliation jobs.

System design through principles — hashing, collision handling, redirect SLO, cache layers.

Token bucket vs sliding window — SRP for limit policy vs storage; fail-fast at edge.

At-least-once delivery, idempotent consumers, ISP for email/SMS/push channels.

Fan-out on write vs read — trade-off documentation in ADR; eventual consistency at feed boundary.

Strong consistency for ledger, idempotency, audit trail — immutability and append-only events.

Ordering, delivery guarantees, presence — separate concerns (SoC) for message vs presence vs history.

Inverted index separation, eventual indexing, DIP between query parser and retrieval.

Treat LLM as non-deterministic dependency — DIP with LLMPort, timeouts, fallbacks, human escalation.

Retrieval-Augmented Generation — separate retrieval (SRP), generation, and evaluation concerns.

Prompts as versioned artifacts — not scattered strings.

Input/output filters, PII redaction, rate limits — fail-fast on policy violation.

Ship AI features with eval harness — golden sets, regression on model/prompt changes.

High-stakes decisions require human confirmation — principle of least astonishment for users.

Lead through clarity, standards, and multiplied impact — not heroics or gatekeeping.

Teach smells and refactor moves — not answers.

Standards where divergence hurts (security, observability); autonomy where it helps (domain models).

RFCs state forces, options, trade-offs, decision — staff template used org-wide.

Psychological safety + high standards — reviews teach, don't punish.

Promotion case: scope, impact, principles applied at org scale — brag doc with metrics.

God class workshop — 450-line OrderManager: list smells, map to SRP, extract in 4 safe steps with tests.

DIP workshop — concrete PostgresUserRepository inside UserService — introduce port, fake, wire DI.

Feature envy workshop — ReportGenerator reaches into Order line items — move method to Order.

Long parameter list — 12-parameter createUser — introduce parameter object or builder with validation.

Switch workshop — discount switch grows weekly — apply OCP with Strategy registry.

Parallel change (Expand-Contract) — migrate API shape without breaking clients — Fowler branch by abstraction.