coding-standards

Coding Standards

Inspect the repository before introducing patterns, libraries, or abstractions. Follow compatible local conventions; contain incompatible legacy patterns at the nearest boundary instead of spreading them into new code.

The examples use TypeScript syntax, but the principles apply across languages. Adapt them to the language and ecosystem already in use.

Priorities

1. Correctness, safety, and debuggability.
2. Explicit domain meaning and dependencies.
3. Compatibility with sound project conventions.
4. The narrowest change that fully solves the requested behavior.
5. Documentation for surprising, durable trade-offs.

Parse at boundaries

Turn unknown or loosely shaped input into application and domain types as early as possible.

unknown -> protocol input -> parser -> domain/application input

A parser returns the refined value or an explicit parsing failure. Do not validate input and then continue carrying the original primitive or transport shape.

Use constrained domain types where they prevent realistic mistakes: identifiers, URLs, email addresses, money, units, constrained numbers, and non-empty values. Construct them through parsers or smart constructors.

Expected failures are values

Known failures belong in explicit return types or equivalent language constructs. This includes parsing, authorization, configuration, persistence, I/O, integration, and workflow failures.

type Result<T, E extends Error> =
  | { readonly _tag: "ok"; readonly value: T }
  | { readonly _tag: "err"; readonly error: E };

Translate dependency-specific exceptions inside the adapter that owns that dependency. Reserve throws, panics, or equivalent mechanisms for defects and impossible internal states. At entrypoints, turn expected failures into valid protocol outcomes: responses, exit codes, retry decisions, dead letters, or startup messages.

Errors should have a stable category, useful safe context, and preserve the original cause where the language supports it. Never put secrets or raw credentials in errors, traces, snapshots, or logs.