Hiding Implementation
In this pack:
sizing,
notation,
rule strictness.
Overview
Every module should keep a secret: one design decision that is likely to
change, such as a storage layout, an algorithm or an outside system's
protocol. Callers ask for an outcome in their own words, and the module
translates at its edge. This skill draws module lines around decisions
rather than around the steps of a process, keeps each class's interface
smaller than the work behind it, and stops storage, format and errors
from crossing the line. A change to the secret then has one place to go.
When to use
- Many classes read or write another class's storage, row or format.
- Callers handle a class's internal errors, or a database's own codes.
- Callers must send several messages in a fixed order to get one job
done.
- A public method hands back an index, a row, a file line or a field
order.
- Two modules must change together for one decision, such as a format
one writes and the other reads.
- A class's interface is about as long as its code.
- A method is named for one screen, and the next caller cannot use it.
When not to use
Core rules
Rule. Give each module a secret: one design decision likely to
change, kept inside. A storage format, an algorithm and an outside
system's protocol are the usual secrets. Draw module lines around
those decisions, not around the steps of a process, so that no
caller's code depends on a decision the module may revise.
Default. Make a class deep: a small interface over substantial
work. When callers must send several messages in a fixed order to
get one job done, give the class one message that does the whole job.
The callers then ask for an outcome and the class keeps how it gets
there.
The exception is a sequence the caller must control, such as steps a
person confirms one at a time. Then the caller owns the pace, and the
messages stay apart.
Rule. Let nothing about the implementation cross the interface.
Names, parameters, results and errors speak in the caller's terms. A
caller of Appointments.add never sees a table, a row or the
database's own error code. The adapter behind the port is the only
place that names the table, and it translates at that edge.
Judgement. Decide whether a call that would change nothing fails by
whether its caller must learn of it. Releasing a slot that is
already free leaves it free, as notation.md's Slot.release does,
because no caller acts on that. A repeated join or cancel may hide a
caller's mistake instead, so the pack's WaitingList.join raises
AlreadyWaiting and Appointment.cancel raises
AppointmentNotCancellable. What tips the balance is whether a caller
would do anything different on hearing of it.
Rule. Keep one decision in one module. When two modules must
change together for one decision, such as a format one of them writes
and the other reads, move that decision into one of them. The other
sends a message and no longer spells the format.
Judgement. Make an interface somewhat general: shaped for what its
callers need across the next changes, not for one caller's screen and
not for every caller that might exist. What tips the balance is
whether the next caller could use a method as it is. A method named
for one screen leaks that screen into the module, and a method so
general that every caller writes the same glue leaks the work back
out.
Pattern
Before, DayPlan stores a day as fifteen-minute blocks and makes every
caller work with them. CallCentre.book asks for an index, reads the
block and writes it, so the caller tests the block and raises the error.
After, DayPlan keeps the blocks and the index private and answers one
message that does the whole booking.
Before:
class DayPlan
- blocks: List<PatientId?>
- opensAt: DateTime
- blockLength: Duration
+ new(entries: List<PatientId?>, opensAt: DateTime,
blockLength: Duration)
blocks := entries.copy()
+ blockIndex(startsAt: DateTime): Int
return startsAt.blockIndexFrom(opensAt, blockLength)
+ blockAt(index: Int): PatientId?
return blocks.at(index)
+ setBlock(index: Int, patient: PatientId?): void
blocks.replace(index, patient)
class CallCentre
- plan: DayPlan
+ new(plan: DayPlan)
+ book(startsAt: DateTime, patient: PatientId): void
raises SlotTaken
index := plan.blockIndex(startsAt)
if plan.blockAt(index) = null then
plan.setBlock(index, patient)
else
raise SlotTaken
return
After:
class DayPlan
- blocks: List<PatientId?>
- opensAt: DateTime
- blockLength: Duration
+ new(entries: List<PatientId?>, opensAt: DateTime,
blockLength: Duration)
blocks := entries.copy()
+ reserve(startsAt: DateTime, patient: PatientId): void
raises SlotTaken
index := indexOf(startsAt)
if blocks.at(index) = null then
blocks.replace(index, patient)
else
raise SlotTaken
return
+ isFree(startsAt: DateTime): Boolean
return blocks.at(indexOf(startsAt)) = null
- indexOf(startsAt: DateTime): Int
return startsAt.blockIndexFrom(opensAt, blockLength)
class CallCentre
- plan: DayPlan
+ new(plan: DayPlan)
+ book(startsAt: DateTime, patient: PatientId): void
plan.reserve(startsAt, patient)
return
The block list arrives through the constructor and is copied, so a
caller that later changes its own list cannot change the plan.
entries.copy() makes a new list with the same entries. The opening time
and the block length arrive as constructor parameters named for their
fields, so the constructor sets both. blocks.at(index) is taken to mean
the entry at that position, and blocks.replace(index, patient) is taken
to mean that the entry at that position is replaced once.
startsAt.blockIndexFrom(opensAt, blockLength) is taken to mean the
position of the block of that length that begins at that time; indexOf
is the one private place that asks, so no caller does arithmetic.
isFree asks the same question as the test inside reserve and changes
nothing. reserve tests one block once, sets it once, and raises
SlotTaken without changing anything when it is taken. CallCentre.book
sends one message. A change to the block size now touches DayPlan and
the one place that builds it.
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 public method whose name or result exposes storage, such as an
index, a row or a raw format.
- Callers that send several messages in a fixed order to get one job
done.
- An outside system's or a database's own error handled far from the
code that called it.
- The same format, limit or constant known in two or more modules.
- A class whose interface is about as long as its code.
Common mistakes
- Making every field private but adding a getter and a setter for each,
which hides nothing.
- Splitting a job into classes by the order its steps run, so each class
knows the same format.
- Wrapping an outside library one method for one method and calling it
hidden.
- Raising an error for a case that changes nothing, so every caller
writes the same check.
- Making an interface general for callers that do not exist yet.
Related skills
Further reading
1---2name: oo-hiding-implementation3description: Use when many classes know how another stores or formats data, when callers must handle its internal errors, or must call its steps in order.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-hiding-implementation7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Hiding Implementation1213**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## Overview1920Every module should keep a secret: one design decision that is likely to21change, such as a storage layout, an algorithm or an outside system's22protocol. Callers ask for an outcome in their own words, and the module23translates at its edge. This skill draws module lines around decisions24rather than around the steps of a process, keeps each class's interface25smaller than the work behind it, and stops storage, format and errors26from crossing the line. A change to the secret then has one place to go.2728## When to use2930- Many classes read or write another class's storage, row or format.31- Callers handle a class's internal errors, or a database's own codes.32- Callers must send several messages in a fixed order to get one job33 done.34- A public method hands back an index, a row, a file line or a field35 order.36- Two modules must change together for one decision, such as a format37 one writes and the other reads.38- A class's interface is about as long as its code.39- A method is named for one screen, and the next caller cannot use it.4041## When not to use4243- The question is who may change an object's state and how:44 [encapsulating state and behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md).45- A caller reaches through a chain of objects to a collaborator:46 [limiting what an object knows](../oo-limiting-what-an-object-knows/SKILL.md).47- Two modules change together, and the question is how tightly they are48 tied or how to measure it:49 [diagnosing coupling](../oo-diagnosing-coupling/SKILL.md).50- The type only carries data, and its fields are its whole meaning:51 [deciding object or data](../oo-deciding-object-or-data/SKILL.md).5253## Core rules54551. Rule. **Give each module a secret: one design decision likely to56 change, kept inside.** A storage format, an algorithm and an outside57 system's protocol are the usual secrets. Draw module lines around58 those decisions, not around the steps of a process, so that no59 caller's code depends on a decision the module may revise.60612. Default. **Make a class deep: a small interface over substantial62 work.** When callers must send several messages in a fixed order to63 get one job done, give the class one message that does the whole job.64 The callers then ask for an outcome and the class keeps how it gets65 there.6667 The exception is a sequence the caller must control, such as steps a68 person confirms one at a time. Then the caller owns the pace, and the69 messages stay apart.70713. Rule. **Let nothing about the implementation cross the interface.**72 Names, parameters, results and errors speak in the caller's terms. A73 caller of `Appointments.add` never sees a table, a row or the74 database's own error code. The adapter behind the port is the only75 place that names the table, and it translates at that edge.76774. Judgement. **Decide whether a call that would change nothing fails by78 whether its caller must learn of it.** Releasing a slot that is79 already free leaves it free, as `notation.md`'s `Slot.release` does,80 because no caller acts on that. A repeated join or cancel may hide a81 caller's mistake instead, so the pack's `WaitingList.join` raises82 `AlreadyWaiting` and `Appointment.cancel` raises83 `AppointmentNotCancellable`. What tips the balance is whether a caller84 would do anything different on hearing of it.85865. Rule. **Keep one decision in one module.** When two modules must87 change together for one decision, such as a format one of them writes88 and the other reads, move that decision into one of them. The other89 sends a message and no longer spells the format.90916. Judgement. **Make an interface somewhat general: shaped for what its92 callers need across the next changes, not for one caller's screen and93 not for every caller that might exist.** What tips the balance is94 whether the next caller could use a method as it is. A method named95 for one screen leaks that screen into the module, and a method so96 general that every caller writes the same glue leaks the work back97 out.9899## Pattern100101Before, `DayPlan` stores a day as fifteen-minute blocks and makes every102caller work with them. `CallCentre.book` asks for an index, reads the103block and writes it, so the caller tests the block and raises the error.104After, `DayPlan` keeps the blocks and the index private and answers one105message that does the whole booking.106107Before:108109```text110class DayPlan111 - blocks: List<PatientId?>112 - opensAt: DateTime113 - blockLength: Duration114 + new(entries: List<PatientId?>, opensAt: DateTime,115 blockLength: Duration)116 blocks := entries.copy()117 + blockIndex(startsAt: DateTime): Int118 return startsAt.blockIndexFrom(opensAt, blockLength)119 + blockAt(index: Int): PatientId?120 return blocks.at(index)121 + setBlock(index: Int, patient: PatientId?): void122 blocks.replace(index, patient)123124class CallCentre125 - plan: DayPlan126 + new(plan: DayPlan)127 + book(startsAt: DateTime, patient: PatientId): void128 raises SlotTaken129 index := plan.blockIndex(startsAt)130 if plan.blockAt(index) = null then131 plan.setBlock(index, patient)132 else133 raise SlotTaken134 return135```136137After:138139```text140class DayPlan141 - blocks: List<PatientId?>142 - opensAt: DateTime143 - blockLength: Duration144 + new(entries: List<PatientId?>, opensAt: DateTime,145 blockLength: Duration)146 blocks := entries.copy()147 + reserve(startsAt: DateTime, patient: PatientId): void148 raises SlotTaken149 index := indexOf(startsAt)150 if blocks.at(index) = null then151 blocks.replace(index, patient)152 else153 raise SlotTaken154 return155 + isFree(startsAt: DateTime): Boolean156 return blocks.at(indexOf(startsAt)) = null157 - indexOf(startsAt: DateTime): Int158 return startsAt.blockIndexFrom(opensAt, blockLength)159160class CallCentre161 - plan: DayPlan162 + new(plan: DayPlan)163 + book(startsAt: DateTime, patient: PatientId): void164 plan.reserve(startsAt, patient)165 return166```167168The block list arrives through the constructor and is copied, so a169caller that later changes its own list cannot change the plan.170`entries.copy()` makes a new list with the same entries. The opening time171and the block length arrive as constructor parameters named for their172fields, so the constructor sets both. `blocks.at(index)` is taken to mean173the entry at that position, and `blocks.replace(index, patient)` is taken174to mean that the entry at that position is replaced once.175`startsAt.blockIndexFrom(opensAt, blockLength)` is taken to mean the176position of the block of that length that begins at that time; `indexOf`177is the one private place that asks, so no caller does arithmetic.178`isFree` asks the same question as the test inside `reserve` and changes179nothing. `reserve` tests one block once, sets it once, and raises180`SlotTaken` without changing anything when it is taken. `CallCentre.book`181sends one message. A change to the block size now touches `DayPlan` and182the one place that builds it.183184## Red flags185186Places to look, not verdicts. A red flag becomes a finding only with187evidence: a measurement, a reproducible bug, or a failing test.188189- A public method whose name or result exposes storage, such as an190 index, a row or a raw format.191- Callers that send several messages in a fixed order to get one job192 done.193- An outside system's or a database's own error handled far from the194 code that called it.195- The same format, limit or constant known in two or more modules.196- A class whose interface is about as long as its code.197198## Common mistakes199200- Making every field private but adding a getter and a setter for each,201 which hides nothing.202- Splitting a job into classes by the order its steps run, so each class203 knows the same format.204- Wrapping an outside library one method for one method and calling it205 hidden.206- Raising an error for a case that changes nothing, so every caller207 writes the same check.208- Making an interface general for callers that do not exist yet.209210## Related skills211212- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule213 labels.214- [oo-encapsulating-state-and-behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)215 keeps state behind messages named for the action.216- [oo-limiting-what-an-object-knows](../oo-limiting-what-an-object-knows/SKILL.md)217 removes a chain or a middle man that hides no decision.218- [oo-diagnosing-coupling](../oo-diagnosing-coupling/SKILL.md) measures219 how tightly two parts are tied before this skill removes the tie.220221## Further reading222223- [Secrets and depth](references/secrets-and-depth.md)224- [Leaks](references/leaks.md)