Engineering Heuristic Catalog

Use a heuristic only when repository evidence makes its expected benefit plausible. These are candidate explanations, not policy inferred from one repository. Each entry includes counter-pressure and a way to test the advice.

Code Clarity

Reveal intent in names and units

• Helps when a reader must mentally simulate a long routine or decode generic names before finding the business rule.
• Can hurt when extraction scatters one simple flow across many tiny functions or renaming replaces familiar domain language.
• Example: replace process(data) with a domain verb, or extract the tax decision from a mixed parse-calculate-persist routine, only when the new boundary tells the story more directly.
• Verify by tracing one representative change: count the files and jumps needed to locate the rule, then run its focused behavior test.

Remove duplication after the shared concept is stable

• Helps when multiple copies represent the same rule and must change together.
• Can hurt when similar-looking code serves different policies; premature unification couples their future changes.
• Example: share one currency-rounding rule used by three invoices, but keep two coincidentally similar validation flows separate when their owners differ.
• Verify by inspecting change history or tests for common reasons to change and by changing one case without breaking the others.

SOLID And Design

Group code by reason to change

• Helps when one module mixes responsibilities owned by different actors or changes for unrelated reasons.
• Can hurt when splitting a cohesive, stable module creates ceremony and coordination overhead.
• Example: separate pricing policy from HTTP serialization when product and protocol changes evolve independently.
• Verify with recent diffs, ownership evidence, and dependency-focused tests: do unrelated changes stop touching the same unit?

Put abstractions at volatile boundaries

• Helps when business policy depends directly on an unstable external service, storage detail, clock, or framework and needs independent testing.
• Can hurt when an interface has one stable implementation and merely mirrors it, increasing navigation without isolating volatility.
• Example: isolate a payment gateway contract, but do not wrap every standard library call.
• Verify by substituting the boundary in a focused test and by checking whether a likely provider change stays outside the policy code.

Prefer substitutable contracts over type tests

• Helps when callers branch on concrete subtype and every new implementation requires another branch.
• Can hurt when variants genuinely have different capabilities and a single contract would hide invalid operations.
• Example: let delivery methods implement a common quote operation only if all can honor its preconditions; otherwise model capabilities explicitly.
• Verify with contract tests across implementations and tests for rejected unsupported operations.

Testing

Test observable behavior at the narrowest trustworthy boundary

• Helps when tests can protect a user-visible rule without binding to internal steps.
• Can hurt when an isolated test misses serialization, persistence, timing, or integration failures at the real boundary.
• Example: unit-test discount rules, then keep one API-and-database test for the wiring that matters.
• Verify by introducing a representative logic defect and a representative integration defect; the appropriate test should fail for each.

Keep doubles at owned seams

• Helps when a slow or nondeterministic external dependency prevents fast, controlled feedback.
• Can hurt when mocks reproduce third-party behavior inaccurately or assertions lock tests to call order instead of outcomes.
• Example: fake an owned payment-port interface in policy tests and retain a provider sandbox contract test.
• Verify by comparing the double with the real boundary and by refactoring internal calls without changing behavior.

Exercise composition roots and shipped artifacts

• Helps when isolated units pass but startup wiring, lifecycle hooks, generated output, or host configuration determines delivered behavior.
• Can hurt when every unit change triggers a slow end-to-end suite; keep a small smoke path for each material composition root and artifact.
• Example: a framework auto-starts run, then page code calls run again, so one page creates two canvases. Invoke one composition root exactly once and verify one root instance. Likewise, make a browser build fail on a missing bundle and smoke-test the actual generated file rather than source or a stale artifact.
• Verify by starting through the production entrypoint, counting created roots or registered handlers, forcing a build error, and loading the cleanly built artifact in its real host.

Make automation failure honest

• Helps when a build, test, or QA wrapper catches a failure, prints a warning, and still exits successfully.
• Can hurt when an unavailable optional check is intentionally non-blocking; label that result skipped or degraded instead of silently redefining it as success.
• Example: if compilation fails but browser QA accepts generic tool output, an old bundle can produce a false green. Propagate the failing exit status and require evidence from the artifact produced by that run.
• Verify by injecting a compile or launch error: the owning check must fail, and removing a generated artifact must not leave the workflow green.

Boundary Data And Adapter Semantics

Decode, validate, and recover at input boundaries

• Helps when persisted settings, files, environment values, or messages can be malformed, stale, wrong-typed, or hostile before entering trusted state.
• Can hurt when permissive fallback hides corruption or a required migration; choose reject, default, quarantine, or repair using repository-owned policy.
• Example: syntax-valid persisted data contains a string where startup expects an integer. Parse with a non-evaluating decoder, validate the schema and ranges, then use the repository-approved fallback so one bad record does not crash every launch.
• Verify with malformed syntax, valid-but-wrong types, unknown fields, dangerous reader forms, and migration fixtures; observe the chosen fallback and ensure no input is executed.

Pass external values as data

• Helps when caller-controlled values cross an interpreter boundary such as a shell, query language, template, or reflective reader.
• Can hurt when replacing a tiny, fixed command with a complex abstraction obscures its behavior; first establish whether the value is actually controllable.
• Example: pass a caller path as a process argument instead of concatenating it into shell source, because quoting a value inside a command string can still allow another round of expansion.
• Verify with spaces, quotes, substitution markers, option-like prefixes, and platform-specific separators; the callee must receive the exact value.

Preserve semantics across adapters

• Helps when multiple hosts implement one core contract but differ in clocks, resize lifecycle, retries, ordering, or error behavior.
• Can hurt when the adapters intentionally expose different product semantics; document that distinction instead of forcing accidental parity.
• Example: adding 1/60 per callback makes a real-time simulation run at half speed when callbacks arrive at 30 Hz. If the product means wall-clock time, measure elapsed time and apply its documented cap or substeps; use fixed ticks only when deterministic frame-count semantics are intended.
• Verify the same contract through each adapter under delayed frames, pauses, resize, and errors; compare observable outcomes rather than internal calls.

Bound cumulative state at its consumption boundary

• Helps when logs, events, retries, caches, or histories grow for the lifetime of a process although consumers only need new or recent entries.
• Can hurt when full history is an explicit audit requirement; then retention, storage, and backpressure need repository-owned limits instead of truncation.
• Example: after a host plays sound events, drain acknowledged entries, advance a consumer cursor, or retain a bounded window. Otherwise each effect remains reachable and long sessions consume steadily more memory.
• Verify with a long-run test that produces and consumes many events, checks each event is handled as required, and asserts retained state reaches a stable bound.

Refactoring

Separate behavior-preserving restructuring from feature change

• Helps when small steps make regressions and review causality easier to locate.
• Can hurt when forced commit separation creates churn for a trivial local rename or blocks an atomic migration that cannot exist halfway.
• Example: characterize a legacy parser, extract a seam, then add the new format; keep an inseparable schema-and-reader migration atomic.
• Verify that tests pass before and after each safe checkpoint and that diffs make behavior changes identifiable.

Add characterization before changing unclear legacy behavior

• Helps when current behavior is relied on but not specified and a rewrite could erase edge cases.
• Can hurt when it canonizes an obvious defect or snapshots irrelevant output.
• Example: capture representative billing outputs before decomposing the calculator, explicitly excluding a confirmed rounding bug from the contract.
• Verify with production examples, issue history, or owner confirmation that each characterized behavior deserves preservation.

Architecture

Point dependencies toward stable business policy

• Helps when core rules are entangled with frameworks, delivery mechanisms, or storage and need to survive those changes.
• Can hurt in a small CRUD system where layers add mapping and indirection without protecting meaningful policy.
• Example: keep eligibility rules independent of the web framework, while allowing a simple admin record screen to use the framework directly.
• Verify with a dependency inspection and a focused test that executes policy without booting external infrastructure.

Introduce boundaries where change cost justifies them

• Helps when teams, deployment, security, scaling, or change cadence require an explicit seam.
• Can hurt when speculative boundaries fragment transactions, duplicate models, or impose distributed-system costs.
• Example: extract an audit service only after independent retention or access requirements appear, not solely because it is a separate noun.
• Verify with measured change coupling, runtime requirements, and a reversible prototype before a large migration.

Professional Practice

Make uncertainty and commitments explicit

• Helps when hidden assumptions or optimistic estimates create surprise and quality pressure.
• Can hurt when exhaustive caveats obscure a small, reversible task.
• Example: state the unknown migration volume and the observation that will narrow it before committing to a cutover date.
• Verify by tracking assumptions, actual outcomes, and whether the next decision becomes clearer.

Protect the definition of done

• Helps when schedule pressure invites skipped tests, concealed risk, or a completion claim without observable evidence.
• Can hurt when an inherited check is unrelated, flaky, or too expensive for the risk; in that case disclose and repair the proof gap rather than silently treating the check as law.
• Example: require the focused payment test and deployment smoke check for a payment change, not an arbitrary coverage percentage.
• Verify with repository-owned acceptance criteria, executable evidence, and explicit disclosure of any unrun or unreliable proof.