[ccoventry]

Release note: none

Part of #1107: the coding standards future work follows, ahead of the audit that checks the existing code against them.

What changes

• New docs/coding_standards.md, listed in docs/README.md. Ten sections, each rule with its reason:
  1. Organisation: one area per file, size as a prompt, no grab-bag utils modules, logic in the layer that owns it.
  2. Functions: one task per function named for it, no flag arguments, few parameters, no hidden side effects, early returns, pure where there are rules.
  3. Names: the app's own terms, one name per idea, verbs / nouns / yes-no booleans, units in names.
  4. Data and types: named constants, enums over strings, parse at the boundary, no sentinels, no unwrap outside tests.
  5. Errors (on top of CLAUDE.md's): no swallowed errors, one message per failure.
  6. Duplication: look first; third copy gets shared; one source of truth for mirrored values.
  7. Dead code: delete, don't comment out.
  8. Comments (on top of CLAUDE.md's): the code says what, the comment why; doc comments on public items.
  9. Tests: with the logic, named for the behaviour, one behaviour each.
  10. Changes and PRs: one change per PR, refactors apart from behaviour changes, leave touched code a little better.
      Plus which of these tools check today, and lint candidates (Clippy too_many_lines etc., ESLint) not turned on: lint rules change only with the owner's OK.
• CLAUDE.md: a new "Organise as you build" rule that points to the standards (read before writing code, check a PR against them), and the main.js rule reworded: the line budget is a guideline; raise it with a reason when one wiring line is all that's over, never shorten comments to fit, move logic out ([Chore] Move the demo queue's list and selection out of main.js #1106).

For review

The standards are a first draft for the owner to keep, change or drop rule by rule. The numbers (50-line functions, 4 parameters, 1,000 / 600-line files) are prompts to look, not limits; say if they should be different. More rules get added as the #1107 audit decides them.

No code changes.

🤖 Generated with Claude Code

Checked against current guidance (second commit)

The draft was reviewed against the Rust API Guidelines, Google's small-CL and TypeScript guides, Ousterhout's A Philosophy of Software Design and his 2024-25 written exchange with Robert Martin over Clean Code, the defect-density research, and the 2026 study of agent instruction files (sources listed at the end of the doc). What changed:

• Functions: "one task per function" kept, with the guardrail the research and Ousterhout add: split only where the piece has a contract a reader can trust without opening it; never into entangled helpers. Complexity (nesting, branches) is the prompt, not line count, since length alone barely predicts defects.
• Organisation: deep modules (small interface, lots hidden) over many shallow ones; "can the caller stop reading here?" is the test for a split.
• Comments: two kinds. Interface comments carry the contract (what, inputs, returns, failures, side effects), which code and long names can't; implementation comments say why, only where non-obvious. Both sides of the debate agree on the second.
• Names: per-language conventions on top (Rust getters without get_, as_/to_/into_; JS casing per Google); long names are not a substitute for a doc comment.
• Errors: typed errors in the library crates with context added as they rise; define errors out of existence where the "error" is a normal outcome.
• PRs: Google's sizes (~100 lines comfortable, ~1,000 too many); what may ride along (a rename, a stale comment) and what gets its own commit or PR.
• Tools: lint candidates named one by one (Clippy pedantic has false positives); max-lines-per-function dropped as a candidate. The instruction-file study is why the standards live in docs/ and CLAUDE.md only points here.