pragmatic-programmer

Files (7)

• SKILL.md
• broken-windows.md · references/
• contracts-assertions.md · references/
• dry-orthogonality.md · references/
• estimation-portfolio.md · references/
• reversibility.md · references/
• tracer-bullets.md · references/

SKILL.md (first lines)

# The Pragmatic Programmer Framework

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

## Core Principle

**Care about your craft.** Software development is a craft that demands continuous learning, disciplined practice, and personal responsibility. Pragmatic programmers think beyond the immediate problem -- they consider context, trade-offs, and long-term consequences of every technical decision.

**The foundation:** Great software comes from great habits. A pragmatic programmer maintains a broad knowledge portfolio, communicates clearly, avoids duplication ruthlessly, keeps components orthogonal, and treats every line of code as a living asset that must earn its place. The goal is not perfection -- it is building systems that are easy to change, easy to understand, and easy to trust.

## Scoring

**Goal: 10/10.** When reviewing or creating software designs, architecture, or code, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and 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:** When knowledge is duplicated, changes must be made 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)
- Code comments that restate the code violate DRY -- comments should explain *why*, not *what*
- Database schemas, API specs, and documentation are all sources of duplication if not 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 | Define DB connection in one env file, reference everywhere |
| **Validation rules** | Shared schema | Use JSON Schema or Zod schema for both client and server validation |
| **API contracts** | Generate from spec | OpenAPI spec generates types, docs, and client code |
| **Business logic** | Domain module | Tax calculation in one module, not scattered across controllers |
| **Database schema** | Migration-driven | Schema defined in migrations, ORM models generated from DB |

See: [references/dry-orthogonality.md](references/dry-orthogonality.md)

### 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. When you change the database layer, the UI should not break. When you change the auth provider, the business logic should not care.

**Key insights:**
- Ask: "If I dramatically change the requirements behind a particular 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
- Toolkits and libraries that force you to inherit from framework 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 |
| **Configuration** | Environment-driven | Feature flags in config, not `if` branches in business logic |
| **Deployment** | Independent services | Deploy auth service without redeploying payment service |

See: [references/dry-orthogonality.md](references/dry-orthogonality.md)

### 3. Tracer Bullets and Prototypes

**Core concept:** Tracer bullets are end-to-end implementations that connect 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 feedback. You see what the system looks like end-to-end before investing in filling out every feature. Users can 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
- Tracer bullets work when you're "shooting in the dark" -- requirements are vague, architecture is unproven
- If a tracer misses, adjust and fire again -- the cost of iteration is low
- Prototypes should be clearly labeled as throwaway -- never let a prototype become production code

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **New project** | Vertical slice | Build one feature end-to-end: button -> API -> DB -> response |
| **Uncertain tech** | Spike prototype | Test if WebSocket performance is sufficient before committing |
| **Framework eval** | Tracer through stack | Build login flow through the full framework before choosing it |
| **Microservice** | Walking skeleton | Deploy a hello-world service through the full CI/CD pipeline |
| **Data pipeline** | End-to-end flow | One record from ingestion through transformation to output |

See: [references/tracer-bullets.md](references/tracer-bullets.md)

### 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 class invariants (what is always true). When a contract is violated, fail immediately and loudly.

**Why it works:** Contracts make assumptions explicit. Instead of silently corrupting data or limping along in an invalid state, the system crashes at the point of the problem -- making bugs visible and traceable. Dead programs tell no lies.

**Key insights:**
- Preconditions: caller's responsibility -- "I accept only positive integers"
- Postconditions: routine's guarantee -- "I will return a sorted list"
- Invariants: always true -- "Account balance never goes negative"
- Crash early: a dead program does far less damage than a crippled one
- Use assertions for things that should never happen; use error handling for things that might
- In dynamic languages, implement contracts through runtime checks and guard clauses

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Function entry** | Precondition guard | `assert age >= 0, "Age cannot be negative"` at function start |
| **Function exit** | Postcondition check | Verify returned list is sorted before returning |
| **Class state** | Invariant validation | `validate!` method called after every state mutation |
| **API boundary** | Schema validation | Validate request body against schema before processing |
| **Data pipeline** | Stage assertions | Assert row count after ETL transform matches expectation |

See: [references/contracts-assertions.md](references/contracts-assertions.md)

From victornovais-dev/sistema_contabilidade, MIT.

More from victornovais-dev/sistema_contabilidade