code-conventions

Code Conventions

A set of conventions distilled from a large, heavily-gated TypeScript codebase. Each one prevents a recurring class of mistake. They are not style preferences; they are rules that keep behavior explicit, reversible, and checked at the right boundary. Apply the ones that fit your codebase's shape; most assume a typed language and module/package boundaries.

The defining constraint: every convention makes one thing unambiguous — where a side effect can be undone, where a decision is made, where a value is validated, and what a swallow actually swallowed.

Reversible side effects

Registrations and contributions are effects, and every effect has a disposer. When a plugin, module, or service contributes something to a shared context — a listener, a schema, a provider, a slot — the registration path returns the function that undoes it. This makes reload and teardown unwind predictably. If a contribution cannot be undone, that is a design gap to name, not something to hide.

Switch on discriminant tags

When a union is closed, exhaustiveness is checked by ending the switch in assertNever. When the union is deliberately open to extension, fall through a documented default rather than a bare default that silently does nothing. The reader should always be able to tell "every case handled and proven" from "unknown case falls through on purpose."

Explicit over implicit at boundaries

Defaulting and choice-making happen at one named step, never hidden inside a downstream call. If a request carries optional fields that must resolve to concrete values, the resolution is an explicit resolve(request) → spec step in the owning implementation — not a ?? default tucked inside run(). A caller reading run() should never have to hunt for the default it applied.

Configuration over hardcoded tunables

Anything that varies by deployment is a validated configuration field, changeable by the operator — not a hardcoded constant or a test-only hook. A DEFAULT_* constant is a code smell for a choice that belongs in config. The inverse also holds: protocol constants, external specifications, and security invariants stay fixed in code; they are not configurable because someone might someday want to change them.