engineering-craft

Engineering craft — code the maintainers would approve

The counterpart to minimalism. Minimalism asks "is this the least code that works?"; craft asks "is the code that remains well-structured, honest, and safe to change?" The target is the intersection: the smallest change that a careful reviewer would approve without asking you to redo it. This is a lens, not a stage — apply it while you implement, and confirm it in self-review before submitting.

Craft is never a licence to add code. When craft and minimalism seem to disagree, they don't: the rule below (real repetition, not speculative) resolves it every time.

The craft bar (hold all of these)

1. Reuse only real repetition — never speculative abstraction. DRY applies to duplication that already exists (the same logic in two places you can see). Do NOT introduce a base class, generic, config system, or "flexible" helper for a second caller that doesn't exist yet — that's the over-engineering minimalism forbids. Rule of thumb: extract on the third occurrence, inline the first two. When you do extract, give the shared unit one clear responsibility.
2. Boundaries at the edges. Keep transport (HTTP/CLI), business logic, and persistence (DB/filesystem) separable — don't put a SQL query or a fetch in the middle of domain logic. Depend on the seam the repo already uses; don't invent a new layering the codebase doesn't have.
3. Handle errors explicitly — no silent failures. No empty catch blocks, no swallowed rejections, no ignored return codes. Either handle the error meaningfully or propagate it with context. A user-facing surface gets a clear message; a server path logs the detail. Never catch {} to make a test pass.
4. Validate at the boundary. Untrusted input (request bodies, CLI args, external API responses, file contents) is checked before use — fail fast with a clear message. Use the repo's existing validation approach (e.g. schema/zod) rather than ad-hoc checks if one exists.
5. Small, focused units. A function does one thing (aim < ~50 lines); a file stays cohesive. If a function has grown a second responsibility or four levels of nesting, split it or use early returns — but only when it genuinely helps clarity, not to hit a number.
6. Honest names. Names say what the thing is/does. Booleans read as is/has/should/can. No data2, tmp, helper, doStuff. A good name removes the need for a comment.
7. Don't mutate what you don't own. Prefer returning new values over mutating shared inputs/state; treat function arguments as read-only unless mutation is the point. Respect the language's idiom — this is immutability where idiomatic (a Go pointer receiver or an in-place sort in hot code is fine); it is not a mandate to copy everything.
8. Composition over inheritance. Reach for a function, a small object, or a passed-in dependency before a class hierarchy.
9. Tests are part of the change. Cover the real logic you added — happy path, the boundaries, and the error cases — not just the line that's easiest to assert. Test code is a guarantee, not bloat (minimalism agrees). Use add-unit-test / add-integration-test for the mechanics.
10. Match the repo, don't reform it. Follow the prevailing conventions, patterns, and style of the code around you. Craft means your addition is indistinguishable from well-written existing code — not that you impose a cleaner paradigm the repo doesn't use. A repo-wide refactor is a separate ticket.