feat(directives): harvest 2 directives from error_handling.md (Result pattern + nil-sentinel)

This commit is contained in:
ed
2026-07-02 21:54:48 -04:00
parent ee36eaed9a
commit 0340925d3e
2 changed files with 188 additions and 0 deletions
@@ -0,0 +1,33 @@
# nil_sentinel_pattern — v1
**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/error_handling.md` §"The 5 Patterns" #1 (lines 23-47).
This is the baseline encoding — the convention-style description with code example currently in production.
Future variants will test alternative encodings (rationale-first, before/after, tabular) against this baseline.
**Source:** `conductor/code_styleguides/error_handling.md:23-47`
---
### 1. Nil-Sentinel Dataclasses (replaces `None`)
When a function would "return None" in conventional Python, return a
nil-sentinel dataclass instead. The sentinel has all default values
(zero-initialized) and is safe to read from.
```python
from dataclasses import dataclass, field
@dataclass(frozen=True)
class NilPath:
exists: bool = False
read_text: str = ""
errors: list[ErrorInfo] = field(default_factory=list)
NIL_PATH = NilPath() # module-level singleton
```
Callers don't need `if x is None:` checks; they can call `x.read_text` and
get `""` on the nil path.
**Convention:** `NIL_*` (uppercase) is the module-level singleton. `Nil*`
(PascalCase) is the class. Frozen dataclass prevents runtime mutation.