Code Guardrails
TDD workflow and quality guardrails. Draws on established practice, including work by R. Martin, K. Beck, B. Meyer, and Toyota's Five Whys.
Golden Rule
No production code without a failing test first. Before changing existing code that has no test, add one that captures its current behavior first.
Evidence Rule
No claim without evidence. Run command, show output, then claim.
Dependency Rule
No new dependency without confirming the standard library or an already-installed dependency cannot do it first.
TDD Cycle (London School)
RED → Write failing test, run it, show failure GREEN → Minimal code to pass, run test, show pass REFACTOR → Clean up, run test + lint, show output
Run ONLY the test you created/changed, not the full suite.
Tests
- Arrange, act, assert. One concept per test.
- The test name states the condition and the expected behavior.
- Independent and repeatable: no shared mutable state, no real clock, network, filesystem, or unseeded randomness.
- Cover every branch and every edge case: empty, single, maximum, off-by-one, transition, and each way the operation can fail.
- Assert observable behavior, never internal state.
- Pure logic is tested without doubles. Orchestration is tested with doubles at its abstractions. Adapters are tested against the real thing.
- Test code follows every rule in this document, same as production code.
- A skipped or ignored test is a defect. Fix it or delete it.
Guiding Principles
| Principle | Meaning |
|---|---|
| KISS | Simplest solution that works |
| YAGNI | Build for now, not hypotheticals |
| DRY | Extract duplication on the third occurrence, not the second (Rule of Three) |
| Single Responsibility (SOLID) | One function = one purpose |
| Boy Scout | Leave code cleaner than you found it |
| Root Cause | Five Whys — fix the source, not the symptom |
Design
- Law of Demeter: talk only to immediate collaborators
- Dependency direction, module depth, and boundary placement: see
/speq-design-philosophy
Functions
- Small and focused
- Few arguments (≤3 ideal)
- No hidden side effects: a function changes nothing its name and contract do not announce
- No boolean flags: split into separate methods
- No selector arguments of any type: an argument that picks a branch means two functions
- One level of abstraction per function: decide or do the work, not both
- A function either mutates something or answers a question, never both in one call (Command-Query Separation)
- No output parameters: return the value
- Guard clauses first. One unindented main path
- No undocumented ordering contract between calls: if a second call requires a first, make it unreachable without it
Errors
- Failure is signalled by the language's own error mechanism, never a sentinel value, magic number, or in-band absent value
- Absence is explicit: an empty collection or the language's optional type, never a stand-in for a value
- Every error states what was attempted, the input that failed, and the constraint violated
- Translate a third-party error into this module's own error type at the boundary: callers never handle a provider's error taxonomy
- Never discard an error, never catch broadly: handle at one level, let the rest propagate
- Errors signal exceptional conditions, not control flow
- The failure path is written test-first, like any other behavior
Naming
- Descriptive, unambiguous, pronounceable
- Named constants over magic numbers
- No prefixes or type encodings
- Types are nouns, functions are verbs, predicates read as questions
- One word per concept across the codebase
- Name length matches scope: single letters only within a few lines
- No role-suffix names that state no responsibility (Manager, Processor, Handler, Data, Info, Util)
- A name reflects what a thing is for, never how it is built: keep transport, vendor, or storage format out of it
- Domain vocabulary over generic programming vocabulary
Comments
- Public/interface methods: brief doc comment stating what the method promises — purpose, and design intent or rationale when that is not self-evident from the signature
- Private methods: no comments
- No inline comments: make the code self-explanatory
- No work tracking (TODOs, FIXMEs, ticket refs)
YAGNI Checks
- Abstraction (interface, generic type, configuration value) with one implementation/caller? Inline it — unless it is a seam over I/O, nondeterminism, or a third party, or the concrete choice is expected to change. Those seams stay.
- Feature flag or extension point nobody uses? Remove it.
Code Smells
| Smell | Signal |
|---|---|
| Rigidity | Small changes cascade everywhere |
| Fragility | One change breaks unrelated code |
| Immobility | Can't reuse code elsewhere |
| Opacity | Hard to understand at a glance |
Attribution
Draws on established practice, including R. Martin (Clean Code, SOLID, Boy Scout Rule), K. Beck (TDD), and B. Meyer (Command-Query Separation).
