0005. Code as prose
- Status: Accepted (provisional)
- Date: 2026-11-14
- Decided by: Mik, on recommendation
- Planning item: D38
Context
Most readers of this code will be agents starting without context. Code that reads top to bottom as an explanation is cheaper to understand, review and change correctly.
Decision
The style guide in CONTRIBUTING.md applies to all Rust and TypeScript: glossary names, top-down files with the entry point first, small single-purpose functions, one concept per file, module doc comments stating ownership and forbidden dependencies, comments that explain why, tests named as sentences.
Function length is a guideline of about 30 lines with a warning, not an error, at 40 (clippy too_many_lines, configured in clippy.toml; a TypeScript lint follows with the first real package). Generated code is exempt.
Alternatives considered
| Option | Why not |
|---|---|
| Hard error at 40 lines | Forces awkward splits of code that reads better whole, such as a parser's main match |
| No limit | The style drifts without a visible signal |
Consequences
CI runs clippy with -D warnings, so a long function must either be split or carry an #[allow(clippy::too_many_lines)] with a reason, which a reviewer sees.