|
@@ -169,6 +169,13 @@ guidelines. Optimising for that reader is not optional polish. Concretely:
|
|
|
- **Explicit over clever.** Idiomatic Python beats micro-optimised trickery —
|
|
- **Explicit over clever.** Idiomatic Python beats micro-optimised trickery —
|
|
|
comprehension over `map`/`filter` chains, dataclasses over dict-shaped blobs,
|
|
comprehension over `map`/`filter` chains, dataclasses over dict-shaped blobs,
|
|
|
early returns over nested conditionals.
|
|
early returns over nested conditionals.
|
|
|
|
|
+- **`if` for states, `try` for faults — line count is not the metric.**
|
|
|
|
|
+ A normal absence ("no client right now") reads as a guard clause;
|
|
|
|
|
+ try/except is reserved for operations that can genuinely fail, with each
|
|
|
|
|
+ except clause stating its own recovery. Folding a state check into an
|
|
|
|
|
+ operation's try saves lines and costs semantics: the shared handler cannot
|
|
|
|
|
+ tell "nothing there" from "server broke", so retry decisions and log blame
|
|
|
|
|
+ go wrong. (The client helpers in `adapter.py` document the split locally.)
|
|
|
- **Docstrings on every public method**, following PEP 257 — plus the override
|
|
- **Docstrings on every public method**, following PEP 257 — plus the override
|
|
|
marker required by *Overriding* below.
|
|
marker required by *Overriding* below.
|
|
|
|
|
|