Honouring Substitutability
In this pack:
sizing,
notation,
rule strictness.
Overview
A subtype stands in for its parent only when it keeps the parent's
contract. Callers are written against that contract: the inputs the parent
accepts, the result and the state it promises, and the errors it allows.
A subtype that accepts less, delivers less or raises more breaks those
callers without changing a line of their code. This skill decides what a
type promises, whether each subtype keeps that promise, and whether a
class should be extended at all.
When to use
- A subclass overrides a parent method and behaves differently from it.
- Callers check which subtype they hold before sending a message.
- A subtype raises an error, or refuses an input, that its parent accepts.
- Two classes share a signature but not the same promise.
- A class is about to be opened to subclasses, or closed to them.
- Tests written for a parent type fail for one of its subtypes.
When not to use
- The subtype only wants its parent's code and is never used where the
parent is expected. That is a question of reuse, not of
substitutability.
- The checks read a type code, an enum or a status field, or cover a
closed set of cases built for exhaustive matching. That is the work of
replacing conditionals with polymorphism, and it is not this skill.
- The type has no subtypes and is already closed to extension. There is
no substitute to honour and no class to open.
Core rules
Rule. Make every subtype usable wherever its parent type is expected,
without the caller knowing which subtype it holds. Callers are
written against the parent's promises, so a subtype that breaks one
breaks them silently. A class that implements an interface is bound by
the same promise as a subclass.
Rule. Never strengthen a precondition in a subtype: accept at least
every input the parent accepts, in every state in which the parent
accepts it. A subtype may accept more than its parent, never less.
Rule. Never weaken a postcondition or drop an invariant in a
subtype: deliver at least what the parent guarantees, keep every
invariant the parent keeps, and raise no error the parent's contract
does not allow. A subtype that returns a different kind of answer,
or leaves the object in a state the parent forbids, breaks callers as
surely as a stronger precondition does.
Default. Write a type's contract where its callers read it: what
each method requires, what it guarantees, and what stays true between
calls. In the notation that is a -- comment under the signature,
after any raises line. A contract kept only in the parent's code is
easy for a subclass author to miss.
The exception is a method whose name, types and raises line already
say all of it, such as a query that accepts any input.
Default. Close a class to extension unless it was built for it.
Built for it means the methods a subclass may override are named,
each with the contract an override must keep written beside it, and
which of the class's own methods send them. An open class that names
no such method invites overrides its author never meant to support.
The exception is a framework that must extend the class at run time,
such as a proxy for lazy loading: leave it open and say in the code
why.
Default. When code checks which subtype it holds before sending a
message, fix the subtype or the hierarchy, not the caller. The check
is the visible sign that a subtype breaks its parent's contract, so
patching the caller that checks does not cure the subtype.
The exception is a closed set of cases built for exhaustive matching,
where each match handles every case and the compiler lists a missing
one.
Judgement. When a subtype cannot keep its parent's contract, either
widen the parent's contract for every subtype or stop extending the
parent. What tips the balance is whether the parent's callers must
handle the new case too: if they must, widen the contract and update
them; if they never meet it, hold the parent instead of extending it.
Pattern
Before, SmsChannel requires a mobile number its interface never asked
for, so a run stops at the first patient without one. After, it hands
that reminder to a channel it holds.
Before:
value Reminder
- patient: PatientId
- text: String
- mobile: String?
+ new(patient: PatientId, text: String, mobile: String?)
+ patient(): PatientId
return patient
+ text(): String
return text
+ mobile(): String?
return mobile
interface ReminderChannel
+ send(reminder: Reminder): void
-- delivers the reminder or hands it on, and raises nothing
class EmailChannel implements ReminderChannel
- mailer: Mailer
+ new(mailer: Mailer)
+ send(reminder: Reminder): void
mailer.send(reminder.patient(), reminder.text())
return
class SmsChannel implements ReminderChannel
- gateway: SmsGateway
+ new(gateway: SmsGateway)
+ send(reminder: Reminder): void
raises NoMobileNumber
mobile := reminder.mobile()
if mobile = null then
raise NoMobileNumber
else
gateway.sendText(mobile, reminder.text())
return
class ReminderRun
- channel: ReminderChannel
+ new(channel: ReminderChannel)
+ run(reminders: List<Reminder>): void
reminders.sendEach(channel)
return
The interface comment says a send delivers the reminder or hands it on,
and raises nothing. EmailChannel keeps that promise. SmsChannel
raises NoMobileNumber when reminder.mobile() is null, an error the
interface does not allow, and it requires a mobile number the interface
never asked for. ReminderRun holds a ReminderChannel, so the error
from the first reminder without a mobile number ends its run and the
later reminders are never sent.
After:
value Reminder
- patient: PatientId
- text: String
- mobile: String?
+ new(patient: PatientId, text: String, mobile: String?)
+ patient(): PatientId
return patient
+ text(): String
return text
+ mobile(): String?
return mobile
interface ReminderChannel
+ send(reminder: Reminder): void
-- delivers the reminder or hands it on, and raises nothing
class EmailChannel implements ReminderChannel
- mailer: Mailer
+ new(mailer: Mailer)
+ send(reminder: Reminder): void
mailer.send(reminder.patient(), reminder.text())
return
class SmsChannel implements ReminderChannel
- gateway: SmsGateway
- fallback: ReminderChannel
+ new(gateway: SmsGateway, fallback: ReminderChannel)
+ send(reminder: Reminder): void
mobile := reminder.mobile()
if mobile = null then
fallback.send(reminder)
else
gateway.sendText(mobile, reminder.text())
return
class ReminderRun
- channel: ReminderChannel
+ new(channel: ReminderChannel)
+ run(reminders: List<Reminder>): void
reminders.sendEach(channel)
return
In the After, SmsChannel holds a second ReminderChannel as
fallback, set by its constructor before send reads it. A reminder
with no mobile number goes to the fallback; every other reminder goes to
the gateway once. SmsChannel accepts every reminder the interface
accepts, raises nothing, and sends each reminder exactly once.
EmailChannel and ReminderRun are unchanged. mailer.send is taken to
email the reminder text to the patient, gateway.sendText to send it as
a text message to that number, and reminders.sendEach(channel) to send
channel.send(reminder) once for each reminder in order, stopping at the
first error.
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.
- An override that raises an error the parent's method never raises.
- An override with an empty body, or one that ignores its input.
- A caller that checks an object's class before sending it a message.
- A subtype method that needs a field or a state its parent's method does
not.
- Tests written for the parent type that a subtype fails.
Common mistakes
- Fixing a broken subtype by adding type checks to every caller.
- Treating a matching signature as a kept contract.
- Leaving a contract only in the parent's code, where a subclass author
never reads it.
- Leaving a class open to extension with no overridable methods named.
- Widening a parent's contract for one subtype without updating the
callers that relied on the narrow one.
Related skills
Further reading
1---2name: oo-honouring-substitutability3description: Use when a subclass throws or breaks its parent's promise, when callers check which subtype they hold, or when deciding if a class may be extended.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-honouring-substitutability7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Honouring Substitutability1213**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## Overview1920A subtype stands in for its parent only when it keeps the parent's21contract. Callers are written against that contract: the inputs the parent22accepts, the result and the state it promises, and the errors it allows.23A subtype that accepts less, delivers less or raises more breaks those24callers without changing a line of their code. This skill decides what a25type promises, whether each subtype keeps that promise, and whether a26class should be extended at all.2728## When to use2930- A subclass overrides a parent method and behaves differently from it.31- Callers check which subtype they hold before sending a message.32- A subtype raises an error, or refuses an input, that its parent accepts.33- Two classes share a signature but not the same promise.34- A class is about to be opened to subclasses, or closed to them.35- Tests written for a parent type fail for one of its subtypes.3637## When not to use3839- The subtype only wants its parent's code and is never used where the40 parent is expected. That is a question of reuse, not of41 substitutability.42- The checks read a type code, an enum or a status field, or cover a43 closed set of cases built for exhaustive matching. That is the work of44 replacing conditionals with polymorphism, and it is not this skill.45- The type has no subtypes and is already closed to extension. There is46 no substitute to honour and no class to open.4748## Core rules49501. Rule. **Make every subtype usable wherever its parent type is expected,51 without the caller knowing which subtype it holds.** Callers are52 written against the parent's promises, so a subtype that breaks one53 breaks them silently. A class that implements an interface is bound by54 the same promise as a subclass.55562. Rule. **Never strengthen a precondition in a subtype: accept at least57 every input the parent accepts, in every state in which the parent58 accepts it.** A subtype may accept more than its parent, never less.59603. Rule. **Never weaken a postcondition or drop an invariant in a61 subtype: deliver at least what the parent guarantees, keep every62 invariant the parent keeps, and raise no error the parent's contract63 does not allow.** A subtype that returns a different kind of answer,64 or leaves the object in a state the parent forbids, breaks callers as65 surely as a stronger precondition does.66674. Default. **Write a type's contract where its callers read it: what68 each method requires, what it guarantees, and what stays true between69 calls.** In the notation that is a `--` comment under the signature,70 after any `raises` line. A contract kept only in the parent's code is71 easy for a subclass author to miss.7273 The exception is a method whose name, types and `raises` line already74 say all of it, such as a query that accepts any input.75765. Default. **Close a class to extension unless it was built for it.**77 Built for it means the methods a subclass may override are named,78 each with the contract an override must keep written beside it, and79 which of the class's own methods send them. An open class that names80 no such method invites overrides its author never meant to support.8182 The exception is a framework that must extend the class at run time,83 such as a proxy for lazy loading: leave it open and say in the code84 why.85866. Default. **When code checks which subtype it holds before sending a87 message, fix the subtype or the hierarchy, not the caller.** The check88 is the visible sign that a subtype breaks its parent's contract, so89 patching the caller that checks does not cure the subtype.9091 The exception is a closed set of cases built for exhaustive matching,92 where each match handles every case and the compiler lists a missing93 one.94957. Judgement. **When a subtype cannot keep its parent's contract, either96 widen the parent's contract for every subtype or stop extending the97 parent.** What tips the balance is whether the parent's callers must98 handle the new case too: if they must, widen the contract and update99 them; if they never meet it, hold the parent instead of extending it.100101## Pattern102103Before, `SmsChannel` requires a mobile number its interface never asked104for, so a run stops at the first patient without one. After, it hands105that reminder to a channel it holds.106107Before:108109```text110value Reminder111 - patient: PatientId112 - text: String113 - mobile: String?114 + new(patient: PatientId, text: String, mobile: String?)115 + patient(): PatientId116 return patient117 + text(): String118 return text119 + mobile(): String?120 return mobile121122interface ReminderChannel123 + send(reminder: Reminder): void124 -- delivers the reminder or hands it on, and raises nothing125126class EmailChannel implements ReminderChannel127 - mailer: Mailer128 + new(mailer: Mailer)129 + send(reminder: Reminder): void130 mailer.send(reminder.patient(), reminder.text())131 return132133class SmsChannel implements ReminderChannel134 - gateway: SmsGateway135 + new(gateway: SmsGateway)136 + send(reminder: Reminder): void137 raises NoMobileNumber138 mobile := reminder.mobile()139 if mobile = null then140 raise NoMobileNumber141 else142 gateway.sendText(mobile, reminder.text())143 return144145class ReminderRun146 - channel: ReminderChannel147 + new(channel: ReminderChannel)148 + run(reminders: List<Reminder>): void149 reminders.sendEach(channel)150 return151```152153The interface comment says a send delivers the reminder or hands it on,154and raises nothing. `EmailChannel` keeps that promise. `SmsChannel`155raises `NoMobileNumber` when `reminder.mobile()` is `null`, an error the156interface does not allow, and it requires a mobile number the interface157never asked for. `ReminderRun` holds a `ReminderChannel`, so the error158from the first reminder without a mobile number ends its run and the159later reminders are never sent.160161After:162163```text164value Reminder165 - patient: PatientId166 - text: String167 - mobile: String?168 + new(patient: PatientId, text: String, mobile: String?)169 + patient(): PatientId170 return patient171 + text(): String172 return text173 + mobile(): String?174 return mobile175176interface ReminderChannel177 + send(reminder: Reminder): void178 -- delivers the reminder or hands it on, and raises nothing179180class EmailChannel implements ReminderChannel181 - mailer: Mailer182 + new(mailer: Mailer)183 + send(reminder: Reminder): void184 mailer.send(reminder.patient(), reminder.text())185 return186187class SmsChannel implements ReminderChannel188 - gateway: SmsGateway189 - fallback: ReminderChannel190 + new(gateway: SmsGateway, fallback: ReminderChannel)191 + send(reminder: Reminder): void192 mobile := reminder.mobile()193 if mobile = null then194 fallback.send(reminder)195 else196 gateway.sendText(mobile, reminder.text())197 return198199class ReminderRun200 - channel: ReminderChannel201 + new(channel: ReminderChannel)202 + run(reminders: List<Reminder>): void203 reminders.sendEach(channel)204 return205```206207In the After, `SmsChannel` holds a second `ReminderChannel` as208`fallback`, set by its constructor before `send` reads it. A reminder209with no mobile number goes to the fallback; every other reminder goes to210the gateway once. `SmsChannel` accepts every reminder the interface211accepts, raises nothing, and sends each reminder exactly once.212`EmailChannel` and `ReminderRun` are unchanged. `mailer.send` is taken to213email the reminder text to the patient, `gateway.sendText` to send it as214a text message to that number, and `reminders.sendEach(channel)` to send215`channel.send(reminder)` once for each reminder in order, stopping at the216first error.217218## Red flags219220Places to look, not verdicts. A red flag becomes a finding only with221evidence: a measurement, a reproducible bug, or a failing test.222223- An override that raises an error the parent's method never raises.224- An override with an empty body, or one that ignores its input.225- A caller that checks an object's class before sending it a message.226- A subtype method that needs a field or a state its parent's method does227 not.228- Tests written for the parent type that a subtype fails.229230## Common mistakes231232- Fixing a broken subtype by adding type checks to every caller.233- Treating a matching signature as a kept contract.234- Leaving a contract only in the parent's code, where a subclass author235 never reads it.236- Leaving a class open to extension with no overridable methods named.237- Widening a parent's contract for one subtype without updating the238 callers that relied on the narrow one.239240## Related skills241242- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule243 labels.244- [oo-choosing-composition-over-inheritance](../oo-choosing-composition-over-inheritance/SKILL.md)245 chooses between extending a class and holding it, which is where a246 subtype that cannot keep its promise ends up.247248## Further reading249250- [Contracts and extension](references/contracts.md)