Fallibility in Signatures
Three return shapes, three meanings:
| Shape | Meaning |
|---|---|
T | āThis doesnāt failā, or āfailure hereās a bug, and a documented oneā. The reviewer should believe it or flag it. |
Option<T> | āAbsence is a normal outcome.ā Lookup misses, exhausted iterators. |
Result<T, E> | āThis can fail, and E says how.ā |
Panics are a fourth shape. A documented panic on a violated
precondition is a legitimate contract: slice indexing works this way, and
so does RefCell::borrow. A function that returns T but panics on
ordinary input has a dishonest signature: that failure path belongs in
the type.
Absence or failure?
The same operation can be modeled either way:
fn signal(&self, name: &str) -> Option<&SignalDef>; // a miss is normal
fn signal(&self, name: &str) -> Result<&SignalDef, UnknownSignal>; // a miss is a defectWhich is right depends on the callers: do they probe for signals that may not exist, or do they name signals that must exist? Decide this in the skeleton. If you donāt, the agent decides it for you, module by module, with no guarantee the modules agree.