git:20260529.9238f59 to git:20260530.d3be4dd

---

name: review-design

description: >

metadata:

title: Pragmatic Programming

category: development

order: 1

---

# Pragmatic Programming

> **Layering:** Principles layer above `assess-quality` (foundational framework) and are operationalized by `write-code` (tool/pattern picks). Use this skill when reasoning about *why* a design tradeoff matters; use `assess-quality` for the underlying quality framework; use `write-code` for concrete picks.

Principles from *The Pragmatic Programmer* (Hunt & Thomas) distilled into actionable rules for everyday development.

## Core Philosophy

- **Care about your craft** why spend your life developing software unless you care about doing it well?

- **Think critically** question assumptions, challenge "because we've always done it that way"

- **Be a catalyst for change** show people a future they can rally around (stone soup)

- **Remember the big picture** don't get so absorbed in details that you forget the system as a whole (boiling frog)

- **Good enough software** know when to stop; perfect is the enemy of shipped

## ETC: Easy to Change

The fundamental design principle. Every decision should make future change easier.

- When choosing between approaches, pick the one that's easier to change later

- If you can't decide which path is more changeable, fall back on: make it replaceable

- Decoupled code is easier to change; single-responsibility code is easier to change; well-named code is easier to change. ETC is the *why* behind all of them

## DRY: Don't Repeat Yourself

> Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

| Violation | Fix |

|-----------|-----|

| Copy-pasted logic | Extract shared function/module |

| Knowledge in code AND comments | Let code be the authority; remove redundant comments |

| Same validation in client and server | Single schema, generate both |

| Repeated config across environments | Template or derive from one source |

| Data structure duplicated across types | Single source type, derive others |

- DRY applies to **knowledge**, not text. Two functions with identical code but representing different knowledge are not DRY violations

- Watch for DRY violations across: code, documentation, data schemas, API specs, build config

## Orthogonality

Keep components independent. Changes in one should not affect others.

- **Test:** If I change X, how many other things must also change? Aim for zero

- Eliminate effects between unrelated things

- Avoid global/shared mutable state

- Prefer composition over inheritance

- Shy code: modules that don't reveal anything unnecessary and don't rely on other modules' implementations

## Reversibility

- Don't commit to a single vendor, platform, database, or architecture prematurely

- Abstract external dependencies behind interfaces

- Prefer configuration over hard-coding

- No critical decisions should be irreversible. If they must be, document and isolate them

## Tracer Bullets

Build thin, end-to-end slices that work, then iterate.

- First version connects all layers (UI to DB) with minimal functionality

- Proves the architecture works, reveals integration problems early

- Different from prototypes: tracer bullet code is kept and built upon

- Use when: requirements are vague, risk is high, or the team hasn't used the stack before

## Prototypes

- Prototype to **learn**, then throw away the code

- Prototypes can ignore: correctness, completeness, robustness, style

- Make it absolutely clear to stakeholders that prototype code is disposable

- Prototype when exploring: architecture, new libraries, UI design, performance approaches

## Estimation

| Duration | Quote in |

|----------|----------|

| 1-15 days | days |

| 3-6 weeks | weeks |

| 8-20 weeks | months |

| > 20 weeks | re-scope before estimating |

- Build a model of the system, identify driving parameters, calculate

- Track your estimates vs. actuals to improve over time

- When asked for an estimate you're not ready to give: "I'll get back to you"

## Design by Contract

- Define **preconditions** (what must be true before), **postconditions** (what's guaranteed after), and **class invariants**

- Crash early. A dead program does less damage than a crippled one

- Use assertions liberally for invariants; don't use them for normal error handling

- Lazy code: be strict in what you accept, promise as little as possible in return

## Pragmatic Paranoia

- **You can't write perfect software** design assuming your code will fail

- Crash early rather than propagate bad state

- Use `try/finally` or equivalent to guarantee resource cleanup

- Assert aggressively. Leave assertions on in production when cost is low

- Don't assume; prove it with assertions and tests

## Decoupling & the Law of Demeter

- **Tell, Don't Ask** tell objects what to do, don't query state and decide for them

- **Law of Demeter** a method should only call methods on: itself, its parameters, objects it creates, its direct fields

- Avoid train wrecks: `a.b().c().d()`. Each dot is a coupling point

- Use events/pub-sub to decouple temporal and structural dependencies

- Prefer: pass in what you need (dependency injection) over reaching out to get it (service locator)

## Transforming Programming

- Think of programs as **data transformations** input -> pipeline of steps -> output

- Prefer pipelines of small transforms over stateful methods that mutate objects

- `|>` thinking: each step takes data, returns transformed data

- Reduces coupling, improves testability, makes data flow visible

## Refactoring

- Refactor **early and often** don't let technical debt compound

- Don't live with **broken windows** fix bad code, bad design, and poor decisions as soon as you see them

- Refactor when you learn something new, not on a schedule

- Disciplined refactoring: keep behavior identical, test before and after, take small steps

## Testing

For per-language conventions, test types, and CI strategy, see the `test-code` skill.

- **Test your software, or your users will**

- Test state coverage, not code coverage. Exercise meaningful paths, not just lines

- Use **property-based testing** to discover edge cases you didn't think of

- Build a test window: logging, diagnostics, hot-key status that lets you peer inside running code

- Test against contract (what it should do), not implementation (how it does it)

- Unit tests are the first users of your API. If tests are hard to write, the design is wrong

## Naming

- A good name captures **intent**, not implementation (`processedItems` not `list2`)

- Name length should be proportional to scope. Short in small lambdas, descriptive in public APIs

- Rename when the name no longer fits. Outdated names are worse than no name

- Naming conventions are a team contract; follow them consistently

## Power of Plain Text

- Keep knowledge in plain text where possible. It outlives all applications

- Config, data formats, build scripts: prefer human-readable formats

- Plain text is self-describing, easier to test, easier to diff, and version-control friendly

## Domain Languages

- Write code in the vocabulary of the problem domain, not the solution domain

- Internal DSLs (fluent APIs, builder patterns) reduce the gap between spec and code

- When the same concept appears repeatedly in different forms, consider whether a mini-language would simplify things

## Pragmatic Teams

- **No broken windows** quality is a team responsibility, not an individual one

- Automate everything: builds, tests, deployments, code formatting

- **Don't outrun your headlights** take small steps, get frequent feedback

- Schedule time to work ON the project (tooling, process), not just IN it