pragmatic-programmer

# The Pragmatic Programmer Framework

A systems-level approach to software craftsmanship from Hunt & Thomas' "The Pragmatic Programmer" (20th Anniversary Edition). Apply these meta-principles when designing systems, reviewing architecture, writing code, or advising on engineering culture -- how to think about software, not just how to write it.

## Core Principle

**Care about your craft.** Software development demands continuous learning, disciplined practice, and personal responsibility -- pragmatic programmers think beyond the immediate problem to context, trade-offs, and long-term consequences. Great software comes from great habits: avoid duplication ruthlessly, keep components orthogonal, and treat every line of code as a living asset that must earn its place. The goal is not perfection -- it is systems that are easy to change, easy to understand, and easy to trust.

## Scoring

**Goal: 10/10.** Rate software designs, architecture, or code 0-10 based on adherence to the principles below; a 10/10 means full alignment, lower scores indicate gaps to address. Always state the current score and the specific improvements needed to reach 10/10.

## The Pragmatic Programmer Framework

Seven meta-principles for building software that lasts:

### 1. DRY (Don't Repeat Yourself)

**Core concept:** Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. DRY is about knowledge, not code -- duplicated logic, business rules, or configuration are far more dangerous than duplicated syntax.

**Why it works:** Duplicated knowledge must be changed in multiple places; eventually one gets missed, introducing inconsistency. DRY reduces the surface area for bugs and makes systems easier to change.

**Key insights:**
- DRY applies to knowledge and intent, not textual similarity -- two identical code blocks serving different business rules are NOT duplication
- Four types of duplication: imposed (environment forces it), inadvertent (developers don't realize), impatient (too lazy to abstract), inter-developer (multiple people duplicate)
- Comments that restate the code violate DRY -- explain *why*, not *what*
- Database schemas, API specs, and documentation duplicate knowledge unless generated from a single source
- The opposite of DRY is WET: "Write Everything Twice" or "We Enjoy Typing"

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Config values** | Single source of truth | DB connection in one env file, referenced everywhere |
| **Validation rules** | Shared schema | One JSON Schema or Zod schema for client and server |
| **API contracts** | Generate from spec | OpenAPI spec generates types, docs, and client code |

See: [references/dry-orthogonality.md](references/dry-orthogonality.md) for the four duplication types and orthogonal design in depth.

### 2. Orthogonality

**Core concept:** Two components are orthogonal if changes in one do not affect the other. Design systems where components are self-contained, independent, and have a single, well-defined purpose.

**Why it works:** Orthogonal systems are easier to test, easier to change, and produce fewer side effects. Change the database layer and the UI should not break; change the auth provider and business logic should not care.

**Key insights:**
- Ask: "If I dramatically change the requirements behind a function, how many modules are affected?" The answer should be one
- Eliminate effects between unrelated things -- a logging change should never break billing
- Layered architectures promote orthogonality: presentation, domain logic, data access
- Avoid global data -- every consumer of global state is coupled to it
- Frameworks that force you to inherit from their classes reduce orthogonality

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Architecture** | Layered separation | Controller -> Service -> Repository, each replaceable |
| **Dependencies** | Dependency injection | Pass a `Notifier` interface, not a `SlackClient` concrete class |
| **Testing** | Isolated unit tests | Test business logic without database, network, or filesystem |

### 3. Tracer Bullets and Prototypes

**Core concept:** Tracer bullets are end-to-end implementations connecting all layers of the system with minimal functionality. Unlike prototypes (which are throwaway), tracer bullet code is production code -- thin but real.

**Why it works:** Tracer bullets give immediate end-to-end feedback before you invest in filling out every feature. Users see something real, developers have a framework to build on, and integration issues surface early.

**Key insights:**
- Tracer bullet: thin but complete path through the system (UI -> API -> DB) -- you keep it
- Prototype: focused exploration of a single risky aspect -- you throw it away
- Use tracer bullets when "shooting in the dark" -- vague requirements, unproven architecture
- If a tracer misses, adjust and fire again -- the cost of iteration is low
- Label prototypes clearly as throwaway -- never let one become production code

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **New project** | Vertical slice | One feature end-to-end: button -> API -> DB -> response |
| **Uncertain tech** | Spike prototype | Test WebSocket performance before committing |
| **Microservice** | Walking skeleton | Hello-world service through the full CI/CD pipeline |

See: [references/tracer-bullets.md](references/tracer-bullets.md) for tracer vs. prototype decisions and walking skeletons.

### 4. Design by Contract and Assertive Programming

**Core concept:** Define and enforce the rights and responsibilities of software modules through preconditions (what must be true before), postconditions (what is guaranteed after), and invariants (what is always true). When a contract is violated, fail immediately and loudly.

**Why it works:** Contracts make assumptions explicit. Ins