Duolith docs

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

OptionWhy not
Hard error at 40 linesForces awkward splits of code that reads better whole, such as a parser's main match
No limitThe 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.