Standards

Coding standards

Enforced by linter, pre-commit hooks, review. Original: ~/.claude/backups/CODING_STANDARDS.md.

Index

  • Structure, Folders, Pipelines: file/function size, one responsibility, stages
  • Naming: functions, booleans, abbreviations
  • Constants and reuse: one definition per repeated value
  • CSS units: rem only, spacing tokens
  • Shared UI styling: one shared style per kind of UI thing
  • Comments, File headers, Context docs, ADRs: what to write where
  • Interfaces, Errors: signatures, typed errors
  • Tests, Linter: TDD, naming, ESLint rules
  • Commits, Version control: messages, branches, merges
  • Security: SQL, shell, secrets, authz, deps
  • Per-file / Per-merge checklists

Structure

  • One responsibility per file (summary has no "and"). Class: 1 job, >5–7 public methods → split.
  • Function ≤30 lines (hard 50). File ≤200 (soft 400, >600 = problem). No god files.

Naming

  • Functions: say what they do incl. side effects. No process, handle, update, check, run.
    • e.g. validateAndNormalizeUserInput, onPaymentWebhookReceived, syncUserProfileToDatabase, isEmailFormatValid
  • Files: name by contents, never utils.js. Organise by domain: payments/formatCurrency.js.
  • Variables: no single letters (except i/j/math). Booleans is/has/can. Full nouns. Spell out abbreviations (URL/ID/API ok).

Constants and reuse (same fact = one definition)

  • A value that means the same thing in 2+ places gets one named constant. Applies to status/kind strings, units (DAY_MS), limits (bytes, lengths), storage keys, header values, regexes.
  • Not a "wrong abstraction": a constant is one fact written once. "Prefer duplication" (see Folders) covers behaviour, not values.
  • Same number, different meaning (e.g. two 200s) = two names, never merged.
  • Where: nearest feature constants file; used in 2+ features → shared/. Build-less frontend that can't import the backend: one copy per side, a comment naming the mirror, a test that both agree.
  • Enum-like values: export an object (STATUS.SENT), build validation Sets from it, and test it against the DB CHECK list.
  • Never rename a stored value (DB, localStorage, API) while centralising it.
  • New code: before typing a literal, grep for an existing constant. Writing a second definition = defect.
  • Add a test that fails if the raw literal returns (e.g. scan source for 86400000).
  • Exempt: 0, 1, -1, HTTP status codes, array indexes, one-use CSS/UI copy.

CSS units (decided 2026-10-18)

  • rem everywhere: spacing, font sizes, widths/heights, radii, media queries. Why: scales with the user's text-size setting; one unit = no px/rem mix.
  • Spacing goes through a rem scale of tokens (--space-1…N, e.g. 0.25 / 0.5 / 1 / 1.5 / 2rem). Raw gap/margin/padding numbers = defect.
  • px exempt only for: borders, outlines, hairlines (1–2px), box-shadow/blur radii.
  • Enforce with a test that scans CSS for px outside the exemptions.

Shared UI styling (decided 2026-10-18, permanent)

  • Each kind of UI thing (button, dropdown, row, card, link, tab, menu, input, dialog) has ONE shared style, defined once, used everywhere. Why: fixing the look in one place fixes it on every page; one-offs drift and clash.
  • New element of a known kind → use the shared class/rule. Never a one-off style for one screen.
  • Style by element, role or shared class (select, .btn-dark, .menu-item), not per-page selectors that repeat the look.
  • Variants change tokens only (custom properties like --c, --space-N), never redeclare the whole look.
  • Looks wrong in one place → fix the shared rule. Element missing the look → give it the shared class; don't copy the styles onto it.
  • OS-drawn widgets (dropdown lists, date pickers): style the element once globally (e.g. appearance: base-select) instead of per-site rebuilds; note which browsers fall back to native.
  • Before writing a style: grep for the shared rule for that kind. A second definition of the same look = defect.
  • Add a test that the shared rule exists and covers the kind (e.g. every <select> matches it).

Comments

  • WHY, not WHAT. Categories: WHY, CONTRACT (pre/postconditions), CONSTRAINT (external limits), TODO/FIXME (with context).
  • No commented-out code (git has history). No stale comments.

Interfaces

  • Typed signatures: Python hints, TS types, JS JSDoc.
  • One return shape, success or error.
  • Pure transforms separate from side-effect functions.
  • Handle errors at module boundary. Internals stay internal.

Pipelines

  • Each stage independently invokable (fetch, match, notify); no skip flags.
  • DB is the contract between stages; stages never call each other.
  • run = thin orchestrator only.
  • Stages idempotent (upsert, not insert). Each commits its output; a later crash keeps earlier work.
  • Why: isolated tests, debuggable, skip costly stages, one reason to change.

Errors

  • Typed, named errors (ValidationError, RateLimitError). No raw strings.
  • Handle where context can decide. Never swallow silently. Never leak stack traces/DB errors to client.

Tests

  • Write first for AI-assisted code. Names describe behavior (test_rejects_email_without_at_symbol), not function names.
  • One behavior per test; "and" in name → split. Assert observable behavior, not internals. No shared mutable state.
  • Types: unit, integration, snapshot, TS type-check in CI.

Linter (JS: ESLint flat config, js.configs.recommended)

  • Rules: max-lines 400, max-lines-per-function 50 (both skip blanks/comments), max-depth 4, no-unused-vars (args ^_), no-undef, eqeqeq.
  • Runs inside the test suite (e.g. tests/lint.test.js) so npm test fails on lint. No formatter rules. Lint owned code only.
  • Existing offenders: one KNOWN EXCEPTIONS block, each line with a ticket number. Never add a file to pass a change. No eslint-disable.

Commits (PLAIN-LANGUAGE-COMMIT-01)

  • Plain, human-readable, intent (what + why, not how). Imperative present tense. Subject ≤50 chars. Body = why.
  • No jargon, no ticket-number-only, no "wip"/"fix stuff"/"updates".
  • Good: skip archived contacts when building the billing run.
  • AI code: message is your reasoning; note what you changed.

Version control

  • Feature branches only, prefixes feature/ fix/ refactor/ chore/. Short-lived; merge, delete.
  • git merge --no-ff. Commit incrementally; each commit one working, tested unit. Tests before implementation.
  • Never commit "just running" state. Tag before big AI refactors.

Folders

  • Feature/domain slices (auth/, payments/, users/, shared/), not technical layers.
  • shared/ = no domain dependency, kept small; prefer duplication to wrong abstraction.
  • Layer-sliced legacy → add context.md/AGENTS.md mapping domains to files.

File headers (every non-trivial file)

  • Lines: purpose (1 sentence); Depends on:; Called by:; IMPORTANT: constraints; Never: prohibitions.

ADRs (docs/decisions/NNN-title.md, 10–20 lines)

  • Fields: Status, Context, Decision, Consequences, Alternatives rejected (most important: stops re-litigation).

Context docs

  • Per project: AGENTS.md at root (<500 words: purpose, stack, folders, patterns, never-do, key decisions + ADR links), docs/decisions/, .ai/ (session state, logs).
  • Session start: read AGENTS.md → one-pass check of today's files (single responsibility? independent modules? skip flags/god files?). Once per session, one sentence, no ceremony. Then relevant ADRs, file headers, task with constraints.

Security

  • Parameterised SQL only. No user input in shell.
  • No hardcoded secrets (env/secrets manager). Escape HTML output.
  • Check ownership, not just auth. Rate-limit login/reset/destructive endpoints.
  • No internal errors to client. Audit new deps (npm audit/pip-audit).
  • Never let AI write unreviewed: auth/sessions, crypto, access control, payment flows beyond SDK.

Per-file checklist (before commit)

  • Header present; function ≤30 lines; file ≤200; npm test incl. lint passes, no new exceptions.
  • Descriptive names; WHY comments; no dead code; no hardcoded secrets/magic strings or repeated literals (see Constants and reuse).
  • Explicit error handling. AI code: every import/method verified to exist.

Per-merge checklist (PR or local merge)

  • Branch prefix; commits pass PLAIN-LANGUAGE-COMMIT-01; tests first/alongside, behavior-named.
  • AGENTS.md and ADR updated if architecture changed.
  • Security check if touching input/auth/storage/external services; deps audited.
  • AI code: can explain every non-trivial block.