coding-standards

Coding Standards

“Thus, programs must be written for people to read, and only incidentally for machines to execute.”
— Abelson and Sussman, Structure and Interpretation of Computer Programs

“In this connection it might be worth-while to point out that the purpose of abstracting is not to be vague, but to create a new semantic level in which one can be absolutely precise.”
— Edsger W. Dijkstra, “The Humble Programmer”

Good code solves a real problem through a model people can understand, use, change, and repair. It tells the truth at the right grain: concepts named where they matter, valid states made clear, boundaries translated, consequences visible, failures classified, behavior verified, and unnecessary structure deleted.

Borrow design pressure, not ecosystem ceremony: impossible states and explicit failure/effect boundaries from Rust; domain modules and algebraic modeling from ML traditions; anti-corruption boundaries from integration-heavy systems. Translate the idea into the host language's native tools.

Core Tenets

• Code communicates a model. Names, types, modules, tests, and interfaces should reveal what is true in the domain and what must not happen.
• Represent meaning at the right grain. Make important distinctions explicit; do not turn every primitive, parser detail, or storage artifact into domain vocabulary.
• Make valid states and transitions explicit. Prefer states, variants, lifecycle rules, and transition points over boolean blindness, nullable phases, and hidden ordering requirements.
• Shape deep modules. Put cohesive behavior behind low-burden interfaces at real seams; a shallow wrapper mostly gives the same work another name.
• Translate at boundaries. External, persisted, framework-shaped, protocol-shaped, or runtime-hop data should be mapped into the internal model before it reaches core logic.
• Make consequences legible. IO, mutation, time, network, async work, authority, retries, resource cost, and other effects should be visible where they affect reasoning.
• Handle errors as part of the design. Expected failures belong in contracts; defects and operational causes need different recovery, reporting, and diagnostics.
• Verify the real claim. Tests and checks should prove behavior, invariants, transitions, boundaries, and failure modes through real seams, not private choreography.
• Delete what does not carry meaning. Collapse speculative generality, indirection mazes, stale shapes, duplicate concepts, and test-only surfaces unless they protect a real obligation.