Answer prose round 2: the CLI is the wiring code that defaults what changes between runs

This commit is contained in:
2026-10-04 21:53:14 +02:00
parent 54cec00d85
commit 21e0843f12
+3 -3
View File
@@ -48,9 +48,9 @@
- Avoid magic, avoid "clever" solutions, only abstract when the API can clearly describe what is happening.
- Prefer explicit, descriptive names over generic ones (`invoiceRowsService`, not `service`).
* Sane defaults, where a default serves better than an explicit ask.
- A default earns its place where most callers want the same value, a wrong guess does no harm, and the caller can see and change it, as a `--help` line or a documented option shows. Anything else is asked for.
- Defaults live at the program's edge: a CLI, a config file, a library's public API, the code that wires the program together. A library still asks for every input that can change between runs, such as data, the clock and randomness; only the code that wires a program together defaults those, as "Functional core, imperative shell" asks.
- BANNED: a CLI that refuses to run until given `--data-path` and `--seed`, when nearly every run wants the shipped data and fresh randomness. GOOD: it fills both, and `--help` names the flags that override them.
- A default earns its place where most callers want the same value, a wrong guess does no harm, and the caller can see and change it through a `--help` line or a documented option. Anything else is asked for.
- Defaults live at the program's edge: a CLI, a config file, a library's public API. A library still asks for every input that can change between runs, such as data, the clock and randomness; only the code that wires a program together, such as its CLI, defaults those, as "Functional core, imperative shell" asks.
- BANNED: a CLI that refuses to run until given `--data-path` and `--seed`, when nearly every run wants the shipped data and fresh randomness. GOOD: it uses the shipped data and fresh randomness unless a flag overrides them, and `--help` names those flags.
* Functional core, imperative shell.
- Decisions live in pure functions, data in and data out; the shell around them performs the effects and holds no branching of its own.
- Every side effect comes from outside: output, time, randomness, network and storage are injectable, so a test runs exactly the code production runs.