Designing Failure Behaviour
In this pack:
sizing,
notation,
rule strictness.
Overview
When a method cannot do its job it has to tell someone. The ways it can
tell differ: refuse in the clinic's words, report that no value exists,
or stop because nothing above can repair the failure. This skill chooses
among them, groups a module's refusals under one base, checks
preconditions before any change, and translates an error only where it
crosses a boundary. The result is a caller that hears every refusal it
must act on and no fault it cannot repair.
When to use
- A method answers
null when it finds nothing.
- Callers ignore a returned success flag, a number or a message.
- Callers catch every exception and carry on.
- A module's error types are being designed or grouped.
- An absent value reaches callers that each decide differently.
- A method may change several fields before it finds a bad input.
When not to use
- The question is which errors a subclass may raise compared with its
parent. That is
honouring substitutability
rule 3.
- The code is an adapter's handling of one provider's error codes, or
how it maps them into the port's terms. That is
crossing system boundaries
and hiding implementation.
- The question is whether a call that would change nothing should fail
at all. That is
hiding implementation rule 4.
- The code can neither refuse nor find nothing, such as a calculation
over values that are already checked.
- The question is retrying or timing out a call to another system. That
is making work reliable, which
bounds the call and decides what a retry may repeat.
Core rules
Rule. When a command cannot do what it was asked because a clinic
rule refuses it, raise an error named in the clinic's words for that
refusal, such as SlotTaken, and declare it on the method's
raises line. Never answer a success flag, a number or a message
that the caller may ignore. A refusal the caller never hears of
leaves the desk believing in a booking that was never made. Modeling
lifecycles, rule 2, names a refused transition this way; this rule
covers every refusal. Whether a call that would change nothing is
refused at all is hiding implementation, rule 4.
Judgement. Tell a refusal from a fault. A refusal is an outcome
of the clinic's rules that the immediate caller can act on, such as
offering another time when SlotTaken is raised: declare it on each
method its caller must handle it from, and let that caller handle
it. A fault is a failure no caller can repair, such as a broken
invariant or a store that does not answer: only the method that
raises it itself declares it, as
the notation asks of every
raise, together with the port that method implements; every method
above passes it on undeclared, up to one handler at the program's
edge, such as the request handler, which records it and answers a
general failure. What tips the balance is whether the immediate
caller would do anything different on hearing of it. Which errors a
language makes its callers declare is outside this skill; oo-java
rules 4 and 5 decide it for Java.
Default. Give the refusals one module raises a common base error
named for what the module refuses, such as BookingRefused, with
one error type per refusal that callers treat apart, so a caller
handles one refusal by its name or all of them by the base. Never
one error with a code field that callers in several places test,
which is the conditional that
replacing conditionals with polymorphism
rule 1 removes. A port still lists on its raises line each refusal
its implementations raise, by name.
The exception is a module with a single refusal: it needs no base.
Rule. Check a method's preconditions before it changes anything,
and raise at once when one fails: a method that finds a broken
precondition after it has changed a field leaves the object
half-changed. Never carry a value known to be wrong into a later
step, where it fails far from its cause. A constructor does the same
for its input, as
constructing valid objects
rule 3 asks.
Rule. Never answer an absent value through a type that does not
say it may be absent. Where each caller decides for itself what
absence means, declare the optional type, Type?, so the caller
must decide; where absence is an error, raise, as
the repositories skill's
find raises AppointmentNotFound; where every caller would do the
same for the absent case, answer a special case, as rule 6 says.
Default. Answer a special case where every caller would treat an
absent or unusual value alike: an object of the same type that gives
that case's answer, such as self-pay for a patient with no insurer,
which answers the whole fee as the patient's share. A null object
is the special case whose answer is to do nothing. Callers then send
the message with no check, and the rule for the case lives in one
class. A special case keeps every promise of its type, as
honouring substitutability
rule 3 asks, so a null object stands only where doing nothing keeps
them.
The exception is an absence that callers treat differently, or that
a caller must report: declare Type? or raise, as rule 5 says.
Rule. Translate an error where it crosses a boundary, and nowhere
else: the adapter behind a port turns an outside system's failure
into a refusal the port declares, in the clinic's words, or lets it
pass as a fault, as
hiding implementation rule 3,
and
crossing system boundaries
rule 3, keep a provider's errors in its adapter. A layer in between
that catches an error only to raise another gives its caller nothing
more to act on.
Pattern
Before, BillingAccount holds an optional policy, and every method that
needs the policy tests it for null first. After, a Payer answers the
same two questions for an insured and for a self-pay patient, and the
account holds one Payer and never a null.
Before:
value InsurancePolicy
- copayShare: Percentage
+ new(copayShare: Percentage)
+ patientShareOf(fee: Money): Money
return fee.portion(copayShare)
+ insurerShareOf(fee: Money): Money
return fee.minus(patientShareOf(fee))
class BillingAccount
- policy: InsurancePolicy?
+ new(policy: InsurancePolicy?)
+ patientShareOf(fee: Money): Money
if policy = null then
return fee
else
return policy.patientShareOf(fee)
+ insurerShareOf(fee: Money): Money
if policy = null then
return Money.zero()
else
return policy.insurerShareOf(fee)
Money and Percentage are taken to be a money amount and a share of
it. fee.portion(share) is taken to mean that share of the fee,
fee.minus(amount) the fee less the amount, and Money.zero() no
money. Every method and every caller that needs the policy repeats the
null check, and one that forgets it fails on null.
After:
interface Payer
-- the two shares make up the fee
+ patientShareOf(fee: Money): Money
+ insurerShareOf(fee: Money): Money
value InsurancePolicy implements Payer
- copayShare: Percentage
+ new(copayShare: Percentage)
+ patientShareOf(fee: Money): Money
return fee.portion(copayShare)
+ insurerShareOf(fee: Money): Money
return fee.minus(patientShareOf(fee))
value SelfPay implements Payer
+ new()
+ patientShareOf(fee: Money): Money
return fee
+ insurerShareOf(fee: Money): Money
return Money.zero()
class BillingAccount
- payer: Payer
+ new(payer: Payer)
+ patientShareOf(fee: Money): Money
return payer.patientShareOf(fee)
+ insurerShareOf(fee: Money): Money
return payer.insurerShareOf(fee)
InsurancePolicy keeps its field, constructor and both methods.
SelfPay has no field, and its constructor sets nothing. SelfPay is
the special case of rule 6 and keeps Payer's promise that the two
shares make up the fee. The code that opens an account passes
new SelfPay() when the patient has no insurer, so no account holds
null; that code is left out of the fence. Nothing raises and nothing
is stored.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A method whose declared result does not say it may be absent, but
that answers
null.
- A command that answers a number or a flag for success.
- An error type with a code field that callers test.
- A catch that swallows every error and carries on.
- A method that changes a field before it checks its precondition.
- The same check for an absent value repeated in every caller.
Common mistakes
- Raising an error for an answer every caller expects, such as no
appointments today, where an empty list answers it.
- Declaring a fault, such as a store that does not answer, on every
method it passes through.
- Answering a null object where a caller must learn that the value is
missing.
- One base error for the whole system rather than one per module.
- Catching an error only to raise another that tells the caller nothing
more.
Related skills
Further reading
- Refusals and faults
- Absence
1---2name: oo-designing-failure-behaviour3description: Use when a method answers null for nothing found, when callers ignore or catch every exception, or when designing a module's error types.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-designing-failure-behaviour7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Designing Failure Behaviour1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920When a method cannot do its job it has to tell someone. The ways it can21tell differ: refuse in the clinic's words, report that no value exists,22or stop because nothing above can repair the failure. This skill chooses23among them, groups a module's refusals under one base, checks24preconditions before any change, and translates an error only where it25crosses a boundary. The result is a caller that hears every refusal it26must act on and no fault it cannot repair.2728## When to use2930- A method answers `null` when it finds nothing.31- Callers ignore a returned success flag, a number or a message.32- Callers catch every exception and carry on.33- A module's error types are being designed or grouped.34- An absent value reaches callers that each decide differently.35- A method may change several fields before it finds a bad input.3637## When not to use3839- The question is which errors a subclass may raise compared with its40 parent. That is41 [honouring substitutability](../oo-honouring-substitutability/SKILL.md)42 rule 3.43- The code is an adapter's handling of one provider's error codes, or44 how it maps them into the port's terms. That is45 [crossing system boundaries](../oo-crossing-system-boundaries/SKILL.md)46 and [hiding implementation](../oo-hiding-implementation/SKILL.md).47- The question is whether a call that would change nothing should fail48 at all. That is49 [hiding implementation](../oo-hiding-implementation/SKILL.md) rule 4.50- The code can neither refuse nor find nothing, such as a calculation51 over values that are already checked.52- The question is retrying or timing out a call to another system. That53 is [making work reliable](../oo-making-work-reliable/SKILL.md), which54 bounds the call and decides what a retry may repeat.5556## Core rules57581. Rule. **When a command cannot do what it was asked because a clinic59 rule refuses it, raise an error named in the clinic's words for that60 refusal, such as `SlotTaken`, and declare it on the method's61 `raises` line.** Never answer a success flag, a number or a message62 that the caller may ignore. A refusal the caller never hears of63 leaves the desk believing in a booking that was never made. Modeling64 lifecycles, rule 2, names a refused transition this way; this rule65 covers every refusal. Whether a call that would change nothing is66 refused at all is hiding implementation, rule 4.67682. Judgement. **Tell a refusal from a fault.** A refusal is an outcome69 of the clinic's rules that the immediate caller can act on, such as70 offering another time when `SlotTaken` is raised: declare it on each71 method its caller must handle it from, and let that caller handle72 it. A fault is a failure no caller can repair, such as a broken73 invariant or a store that does not answer: only the method that74 raises it itself declares it, as75 [the notation](../oo-design/references/notation.md) asks of every76 `raise`, together with the port that method implements; every method77 above passes it on undeclared, up to one handler at the program's78 edge, such as the request handler, which records it and answers a79 general failure. What tips the balance is whether the immediate80 caller would do anything different on hearing of it. Which errors a81 language makes its callers declare is outside this skill; `oo-java`82 rules 4 and 5 decide it for Java.83843. Default. **Give the refusals one module raises a common base error85 named for what the module refuses, such as `BookingRefused`, with86 one error type per refusal that callers treat apart, so a caller87 handles one refusal by its name or all of them by the base.** Never88 one error with a code field that callers in several places test,89 which is the conditional that90 [replacing conditionals with polymorphism](../oo-replacing-conditionals-with-polymorphism/SKILL.md)91 rule 1 removes. A port still lists on its `raises` line each refusal92 its implementations raise, by name.9394 The exception is a module with a single refusal: it needs no base.95964. Rule. **Check a method's preconditions before it changes anything,97 and raise at once when one fails: a method that finds a broken98 precondition after it has changed a field leaves the object99 half-changed.** Never carry a value known to be wrong into a later100 step, where it fails far from its cause. A constructor does the same101 for its input, as102 [constructing valid objects](../oo-constructing-valid-objects/SKILL.md)103 rule 3 asks.1041055. Rule. **Never answer an absent value through a type that does not106 say it may be absent.** Where each caller decides for itself what107 absence means, declare the optional type, `Type?`, so the caller108 must decide; where absence is an error, raise, as109 [the repositories skill](../oo-designing-repositories/SKILL.md)'s110 `find` raises `AppointmentNotFound`; where every caller would do the111 same for the absent case, answer a special case, as rule 6 says.1121136. Default. **Answer a special case where every caller would treat an114 absent or unusual value alike: an object of the same type that gives115 that case's answer, such as self-pay for a patient with no insurer,116 which answers the whole fee as the patient's share.** A null object117 is the special case whose answer is to do nothing. Callers then send118 the message with no check, and the rule for the case lives in one119 class. A special case keeps every promise of its type, as120 [honouring substitutability](../oo-honouring-substitutability/SKILL.md)121 rule 3 asks, so a null object stands only where doing nothing keeps122 them.123124 The exception is an absence that callers treat differently, or that125 a caller must report: declare `Type?` or raise, as rule 5 says.1261277. Rule. **Translate an error where it crosses a boundary, and nowhere128 else: the adapter behind a port turns an outside system's failure129 into a refusal the port declares, in the clinic's words, or lets it130 pass as a fault, as131 [hiding implementation](../oo-hiding-implementation/SKILL.md) rule 3,132 and133 [crossing system boundaries](../oo-crossing-system-boundaries/SKILL.md)134 rule 3, keep a provider's errors in its adapter.** A layer in between135 that catches an error only to raise another gives its caller nothing136 more to act on.137138## Pattern139140Before, `BillingAccount` holds an optional policy, and every method that141needs the policy tests it for `null` first. After, a `Payer` answers the142same two questions for an insured and for a self-pay patient, and the143account holds one `Payer` and never a `null`.144145Before:146147```text148value InsurancePolicy149 - copayShare: Percentage150 + new(copayShare: Percentage)151 + patientShareOf(fee: Money): Money152 return fee.portion(copayShare)153 + insurerShareOf(fee: Money): Money154 return fee.minus(patientShareOf(fee))155156class BillingAccount157 - policy: InsurancePolicy?158 + new(policy: InsurancePolicy?)159 + patientShareOf(fee: Money): Money160 if policy = null then161 return fee162 else163 return policy.patientShareOf(fee)164 + insurerShareOf(fee: Money): Money165 if policy = null then166 return Money.zero()167 else168 return policy.insurerShareOf(fee)169```170171`Money` and `Percentage` are taken to be a money amount and a share of172it. `fee.portion(share)` is taken to mean that share of the fee,173`fee.minus(amount)` the fee less the amount, and `Money.zero()` no174money. Every method and every caller that needs the policy repeats the175`null` check, and one that forgets it fails on `null`.176177After:178179```text180interface Payer181 -- the two shares make up the fee182 + patientShareOf(fee: Money): Money183 + insurerShareOf(fee: Money): Money184185value InsurancePolicy implements Payer186 - copayShare: Percentage187 + new(copayShare: Percentage)188 + patientShareOf(fee: Money): Money189 return fee.portion(copayShare)190 + insurerShareOf(fee: Money): Money191 return fee.minus(patientShareOf(fee))192193value SelfPay implements Payer194 + new()195 + patientShareOf(fee: Money): Money196 return fee197 + insurerShareOf(fee: Money): Money198 return Money.zero()199200class BillingAccount201 - payer: Payer202 + new(payer: Payer)203 + patientShareOf(fee: Money): Money204 return payer.patientShareOf(fee)205 + insurerShareOf(fee: Money): Money206 return payer.insurerShareOf(fee)207```208209`InsurancePolicy` keeps its field, constructor and both methods.210`SelfPay` has no field, and its constructor sets nothing. `SelfPay` is211the special case of rule 6 and keeps `Payer`'s promise that the two212shares make up the fee. The code that opens an account passes213`new SelfPay()` when the patient has no insurer, so no account holds214`null`; that code is left out of the fence. Nothing raises and nothing215is stored.216217## Red flags218219Places to look, not verdicts. A red flag becomes a finding only with220evidence: a measurement, a reproducible bug, or a failing test.221222- A method whose declared result does not say it may be absent, but223 that answers `null`.224- A command that answers a number or a flag for success.225- An error type with a code field that callers test.226- A catch that swallows every error and carries on.227- A method that changes a field before it checks its precondition.228- The same check for an absent value repeated in every caller.229230## Common mistakes231232- Raising an error for an answer every caller expects, such as no233 appointments today, where an empty list answers it.234- Declaring a fault, such as a store that does not answer, on every235 method it passes through.236- Answering a null object where a caller must learn that the value is237 missing.238- One base error for the whole system rather than one per module.239- Catching an error only to raise another that tells the caller nothing240 more.241242## Related skills243244- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule245 labels.246- [oo-hiding-implementation](../oo-hiding-implementation/SKILL.md)247 keeps a provider's types and errors behind its adapter.248- [oo-crossing-system-boundaries](../oo-crossing-system-boundaries/SKILL.md)249 decides which errors a port declares where a provider's API is wrapped.250- [oo-honouring-substitutability](../oo-honouring-substitutability/SKILL.md)251 keeps a special case within its type's promise.252- [oo-constructing-valid-objects](../oo-constructing-valid-objects/SKILL.md)253 checks a constructor's input before the object exists.254- [oo-modeling-lifecycles](../oo-modeling-lifecycles/SKILL.md) names a255 refused transition with the error for it.256257## Further reading258259- [Refusals and faults](references/refusals-and-faults.md)260- [Absence](references/absence.md)