Pragmatic engineering

How a coding agent makes everyday trade-offs: what to build, how much, how reversibly, and when to stop. It distils ideas from The Pragmatic Programmer (Thomas & Hunt) and the Extreme Programming values, in our own words. Read the book for the reasoning; this file says what to do.

Decision procedure

Stop exploring once a step settles the choice, but always price the undo (step 2) before acting, and run steps 4 and 5 on what you do.

1. Name the consumer and the outcome. Who uses the result, and what observable thing proves it works? A present requirement or caller justifies work; a hypothetical one does not.
2. Price the undo. Easy to reverse: decide fast, take the smaller step. Hard to reverse (public API, data format, schema, deletion, shared state): narrow the step and state the rollback first.
3. Spend the cheapest effort that removes the biggest uncertainty. Need a real implementation to grow from: tracer bullet. Need an answer you will throw away: prototype. Nothing unknown: just do it.
4. Get feedback from the real path (test, command, rendered result) before the next step.
5. Leave the touched area no worse, and report what you left undone.

Principle to behaviour

Naming and language

• English throughout the code: identifiers, comments, docstrings, test names, and logs and errors meant for developers. User-facing copy follows the product's locale.
• The ecosystem's convention, enforced by the project's linter:
  • Python (PEP 8): snake_case for functions, variables and modules; PascalCase for classes; UPPER_SNAKE_CASE for constants.
  • JS/TS: camelCase for variables and functions; PascalCase for classes, types and components; UPPER_SNAKE_CASE for module constants.
  • Go: MixedCaps, with an exported name starting with a capital.
  • Rust: snake_case / PascalCase.
  • SQL: snake_case.
  • File names follow the framework's convention.
• Names state intent: verbs for functions (load_invoice), nouns for values, is_/has_ for booleans, units in the name (timeout_s), and no abbreviations beyond the domain's own.
• Comments earn their place: write one only for what the code cannot say — why, a constraint, a non-obvious invariant, a link to the issue or spec. Never restate the code, never narrate history, and delete a comment the change made stale.
• Code already written in another language: new and touched code is English. Do not bulk-rename untouched code.

"Is this over-engineered?"

Ask each question; a bad answer means cut, defer or reuse.

• Is there a present consumer or requirement for it? If not, defer.
• Does an existing mechanism (code, library, platform feature) already do the job? If so, reuse it.
• Can you state in a few sentences why it exists and how it fails? If not, simplify or understand it first.
• Does the abstraction give a present benefit, such as isolating a volatile choice or enabling a test? A single-caller abstraction without one is tidiness, not design.

An extra found in a diff is stripped with kill-slop, keeping the behaviour.

Red flags

• "We might need it later" with no named consumer.
• A flag, layer or config key with one caller and one possible value.
• A copied block whose knowledge now lives in two places.
• A spike that grows tests, config and users without a decision to promote it.
• A TODO, comment or skipped test standing in for a decision about debt on the path you are changing.
• A fix nobody can explain; a big-bang change with no intermediate runnable point.
• A confident estimate or "done" with no evidence behind it.
• Broken-window zeal: fixing everything nearby until the diff cannot be reviewed.

What this is not

• Not a process: no ceremony, planning documents or gates of its own.
• Not a style guide beyond naming and language: it never overrides the repository's conventions or the user's explicit instructions.
• Not a licence to skip tests or safety checks in the name of "simple".
• Not a rule against abstraction: a seam that already pays for itself stays.
• Not a substitute for the book: it records decisions, not the book's arguments or examples.