maintainable-code

Write and review code so the next competent maintainer, with solid fundamentals but none of this session's context, can understand it, test it, and debug its failures in production without a debugger. Match the surrounding code's patterns before applying anything here. For small edits apply these rules silently and mention only decisions that change the result; a rename needs no new tests, comments, failure map or doc research. Load maintainable-tests when adding or changing tests, if available.

Code

• Keep one level of abstraction per function (orchestration, policy, transformation, I/O). Split by stable responsibility, not line count. Extract duplication only when the copies share a reason to change; add an abstraction only with two real call sites or a real boundary to protect. Interfaces with imaginary substitutes and public setters added for tests are worse than a single clear replacement point.
• Prefer typed data shapes over strings and option bags; make invalid states unrepresentable where the language allows.
• Normalize inputs early, guard invalid cases, keep the happy path visible. At entry points keep cancellation, absent optional capability, operational failure and unexpected defects distinct with actionable causes; do not collapse them into false, null or one generic error.
• Refactor non-trivial behaviour only with adequate coverage; reuse existing tests and add characterization only for gaps. Preserve behaviour before polishing structure.
• State consequential tradeoffs in the final answer when you deliberately leave complexity in place. Report key files, verification run and remaining risk; omit empty sections.
• When the user asks for cleverness or compression, do it, keep correctness and types intact, and mention only consequential maintenance costs.

Comments

Comment only non-obvious rationale, invariants, external contracts (API quirks, file formats, rate limits, runtime quirks), the phase of a dense block, and what breaks if a future maintainer "simplifies" it. Rename or restructure before commenting; never narrate syntax and never add comments for the user to prune later. Put each comment at the smallest useful scope: module or class (responsibility, lifecycle), method (side effects, errors, idempotency), field (units, nullability, persisted format, why a weak type is safe), branch or block (invariant, workaround), trailing only for short source notes. Dense operational code (CI YAML, shell pipelines, migrations, generated glue) needs phase names and artifact contracts commented; generated files say how to regenerate.

When a data flow, state machine, retry loop or ownership relationship is hard to follow in prose, put a compact ASCII diagram (+ - | > <, no box drawing) in the docblock, with labels that match real names, and update diagram and prose together; delete it if it cannot be repaired. Back uncertain, version-sensitive or consequential claims about a framework or language with the project's version-matched official docs, paraphrased and linked when that helps a maintainer verify it; do not research known basics.