software-design

# Software Design

Software design is the discipline of organizing code so that it is correct, understandable, and changeable. A well-designed system makes the right things easy and the wrong things hard. This skill catalogs the principles, patterns, and architectural styles that professional software engineers use to achieve this, with emphasis on when each applies and when it does not.

**Agent affinity:** dijkstra (structured programming, formal reasoning about design), kay (OOP, message-passing architecture)

**Concept IDs:** code-code-organization, code-abstraction, code-decomposition, code-peer-review

## Part 1 -- Design Principles

### The SOLID Principles

Robert C. Martin codified these five principles for object-oriented design. They apply more broadly to any modular system.

#### S -- Single Responsibility Principle (SRP)

**Statement:** A module should have one, and only one, reason to change.

**What it means.** Each class, function, or module should serve exactly one purpose. If you change the database schema, only the database layer should change. If you change the UI layout, only the UI layer should change.

**Violation signal.** A class that has methods for both parsing user input AND writing to the database. A function that both validates data AND sends an email.

**Fix.** Separate the responsibilities into distinct modules. A UserValidator validates; a UserRepository persists; an EmailService sends.

#### O -- Open/Closed Principle (OCP)

**Statement:** Software entities should be open for extension but closed for modification.

**What it means.** You should be able to add new behavior without changing existing, tested code. This is achieved through abstraction -- interfaces, abstract classes, or polymorphism.

**Violation signal.** A function with a growing chain of if/else or switch statements that must be modified every time a new case is added.

**Fix.** Define an interface that each case implements. New cases add a new implementation without touching existing code. The Strategy pattern is the canonical implementation of OCP.

#### L -- Liskov Substitution Principle (LSP)

**Statement:** Objects of a supertype should be replaceable with objects of a subtype without breaking the program.

**What it means.** Subclasses must honor the contract of their parent. If a function works with a Shape, it must work with Circle, Rectangle, and Triangle without knowing which one it has.

**The classic violation.** Square extends Rectangle. A function sets width to 5 and height to 10, then asserts area == 50. The Square overrides setWidth to also set height, so area == 100. The substitution broke the contract.

**Fix.** Do not make Square a subclass of Rectangle. Model them as siblings implementing a common Shape interface, or use composition instead of inheritance.

#### I -- Interface Segregation Principle (ISP)

**Statement:** No client should be forced to depend on methods it does not use.

**What it means.** Large interfaces should be split into smaller, more specific ones. A Printer interface with print(), scan(), fax(), and staple() forces a simple printer to implement fax() and staple() with stubs or exceptions.

**Fix.** Split into Printable, Scannable, Faxable. Clients depend only on the interfaces they use. Composition of small interfaces is more flexible than one large interface.

#### D -- Dependency Inversion Principle (DIP)

**Statement:** High-level modules should not depend on low-level modules. Both should depend on abstractions.

**What it means.** The business logic should not import the database driver directly. Instead, both the business logic and the database implementation depend on a Repository interface. This makes the database swappable without changing the business logic.

**Implementation.** Dependency injection: pass dependencies as constructor parameters or function arguments rather than creating them internally. This also enables testing -- inject a mock repository in tests, a real one in production.

### Complementary Heuristics

**DRY (Don't Repeat Yourself).** Every piece of knowledge should have a single, unambiguous, authoritative representation. Duplication is a maintenance liability. But premature de-duplication (abstracting too early) can be worse than duplication -- wait until you see the pattern three times (the Rule of Three).

**KISS (Keep It Simple, Stupid).** The simplest solution that works is the best solution. Complexity is a cost, not a feature. Every abstraction layer, design pattern, and framework adds complexity that must be justified by the problems it solves.

**YAGNI (You Aren't Gonna Need It).** Do not build features, abstractions, or flexibility for hypothetical future requirements. Build what you need now. When the future requirement arrives, you will understand it better and build a more appropriate solution.

**Separation of Concerns.** Each module addresses a separate concern. The UI does not contain business logic. The business logic does not contain database queries. The database layer does not format HTTP responses. This is the meta-principle behind SOLID, MVC, and layered architecture.

### Coupling and Cohesion

**Coupling** measures how much modules depend on each other. Low coupling means modules can be changed independently. High coupling means a change in one module cascades through many others.

**Cohesion** measures how closely related the elements within a module are. High cohesion means a module does one thing well. Low cohesion means a module is a grab-bag of unrelated functionality.

**The goal:** high cohesion within modules, low coupling between modules. This is the quantitative formulation of good design.

## Part 2 -- Design Patterns

Design patterns are reusable solutions to common design problems. They are not code templates -- they are conceptual tools for structuring interactions between objects and modules. The Gang of Four (GoF) cataloged 23 patterns in 1994; the 12 most practically important