Selaa lähdekoodia

Codify the if-for-states/try-for-faults split under Readability

The guard-clause refactor of the client fetches kept regressing to
try/except folding because fewer lines looked cheaper locally. State the
rule where habits are made: a normal absence is a guard clause, an
except clause states its own recovery, and line count never outranks
failure semantics.
Paul Klumpp 1 viikko sitten
vanhempi
commit
ccf80b9525
1 muutettua tiedostoa jossa 7 lisäystä ja 0 poistoa
  1. 7 0
      AGENTS.md

+ 7 - 0
AGENTS.md

@@ -169,6 +169,13 @@ guidelines. Optimising for that reader is not optional polish. Concretely:
 - **Explicit over clever.** Idiomatic Python beats micro-optimised trickery —
   comprehension over `map`/`filter` chains, dataclasses over dict-shaped blobs,
   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
   marker required by *Overriding* below.