Reviewing Object Design
In this pack:
sizing,
notation,
rule strictness.
Overview
A review answers one question for the author: which line of this change
breaks which rule, and what must happen before it merges. It reads the
change, not the whole module, and it keeps the size of the task in view.
A comment that names no rule and shows no evidence is a question, not a
finding. This skill turns a change and the pack's rules into a short set
of findings, each with a verdict.
When to use
- A pull request needs a review for object-design problems.
- A design is ready to read before its code is written.
- A review comment needs the rule behind it, by skill and number.
- An author and a reviewer disagree about whether a finding blocks.
- A review has grown into a long list with no sense of what must change.
When not to use
- A review has already named an antipattern, and the question is what to
do about it: recognising antipatterns
decides the response and its order.
- The question is how to design the change rather than how to review it:
run the index's design loop first, then review the result.
- The change is an answer used once and then thrown away, which the
index's sizing table skips entirely.
- The comment is about formatting that a tool in the build already
checks, such as line length: the tool decides it.
Core rules
Rule. Review a change against what it must keep and against its
size. The change names the rule it implements, with one example it
accepts and one it rejects, as the index's gate asks before
designing. It falls in one row of the index's sizing table. A change
to one method in a class that exists is reviewed for its name and
its contract, not for a new model.
Rule. Report a finding only with the rule it breaks, by skill and
number, and the lines of the change that break it. Before writing
it, read that rule's number, label and statement in the rule's own
skill, reached from the checklist question that names it; take none
of them from memory. A red flag alone is a question to the author
until it has the evidence the index asks for: a measurement, a
reproducible bug or a failing test.
Rule. Weigh a finding by the label of the rule it breaks. The
index defines the three labels under how strictly a rule is meant. A
broken rule labelled Rule. blocks the merge. A broken Default.
blocks unless the change shows that the rule's exception holds. A
Judgement. is discussed, and the author's reasoned choice stands.
A preference that no rule backs, such as a name the reviewer likes
better, never blocks.
Rule. Use the diff checklist for a change to existing code, and
the design checklist for a new module, context or system before its
code is written. Each question in them names the rule that
answers it, and a finding cites that rule, not the checklist.
Default. Ask for the smallest change that keeps the broken rule,
within the lines the change touches. Write a finding about code
the change does not touch as a separate note for later work.
The exception is a defect the change makes worse, such as a second
caller added to a method that already breaks a rule: it is a finding
against this change.
Rule. Review the tests in a change as part of its design. Each
rule the change adds has a test named for that rule that goes
through the object's public messages, as
testing object-oriented code
rules 1 and 3 ask. A rule the change adds with no test at all is a
finding against that skill's rule 2, which writes each test before
its code.
Pattern
Before, the change under review adds attendeeList, a query that
returns the list the class keeps. enrol was there before the change,
so the only line the change adds is attendeeList.
Before:
class AntenatalClass
- attendees: List<PatientId>
+ new()
attendees := new List<PatientId>()
+ enrol(patient: PatientId): void
attendees.add(patient)
return
+ attendeeList(): List<PatientId>
return attendees
After, the change once its one blocking finding is fixed returns a
read-only view. The field, constructor and enrol are unchanged.
After:
class AntenatalClass
- attendees: List<PatientId>
+ new()
attendees := new List<PatientId>()
+ enrol(patient: PatientId): void
attendees.add(patient)
return
+ attendeeList(): ReadOnlyList<PatientId>
return attendees.readOnlyView()
The review has three findings. First, attendeeList hands out the list
the class keeps, so a caller can add a patient without enrol; that
breaks
encapsulating state and behaviour
rule 5, labelled Rule., so it blocks, under rules 2 and 3. Second, a
wish to call the method bookedMothers has no rule behind it, since
attendeeList already names the answer as
naming classes and methods
rule 2 asks, so it does not block, under rule 3. Third, enrol
accepting the same patient twice lies in code the change does not
touch, so it becomes a separate note, under rule 5.
new List<PatientId>() is taken to mean an empty list the class owns.
Both fences store nothing and leave out how the class is stored. Each
version sets attendees in its constructor before enrol or
attendeeList reads 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 review comment with no rule and no evidence behind it.
- A blocking comment on a choice a
Judgement. rule leaves open.
- A request to change code the change does not touch.
- A new rule in the change with no test named for it.
- A review of a one-method change that asks for a new model.
- A long list of comments with nothing marked as blocking or not.
Common mistakes
- Blocking on a name the reviewer would have chosen.
- Letting a broken
Rule. pass because the change is small.
- Reviewing the whole module instead of the change.
- Reporting red flags as findings with no evidence.
- Asking for a redesign where a one-line fix keeps the rule.
Related skills
Further reading
- Diff checklist
- Design checklist
1---2name: oo-reviewing-object-design3description: Use when reviewing a pull request or a design for object-design problems, or when deciding which review findings must block a merge.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-reviewing-object-design7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Reviewing Object Design1213**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 review answers one question for the author: which line of this change21breaks which rule, and what must happen before it merges. It reads the22change, not the whole module, and it keeps the size of the task in view.23A comment that names no rule and shows no evidence is a question, not a24finding. This skill turns a change and the pack's rules into a short set25of findings, each with a verdict.2627## When to use2829- A pull request needs a review for object-design problems.30- A design is ready to read before its code is written.31- A review comment needs the rule behind it, by skill and number.32- An author and a reviewer disagree about whether a finding blocks.33- A review has grown into a long list with no sense of what must change.3435## When not to use3637- A review has already named an antipattern, and the question is what to38 do about it: [recognising antipatterns](../oo-recognising-antipatterns/SKILL.md)39 decides the response and its order.40- The question is how to design the change rather than how to review it:41 run the index's design loop first, then review the result.42- The change is an answer used once and then thrown away, which the43 index's sizing table skips entirely.44- The comment is about formatting that a tool in the build already45 checks, such as line length: the tool decides it.4647## Core rules48491. Rule. **Review a change against what it must keep and against its50 size.** The change names the rule it implements, with one example it51 accepts and one it rejects, as the index's gate asks before52 designing. It falls in one row of the index's sizing table. A change53 to one method in a class that exists is reviewed for its name and54 its contract, not for a new model.55562. Rule. **Report a finding only with the rule it breaks, by skill and57 number, and the lines of the change that break it.** Before writing58 it, read that rule's number, label and statement in the rule's own59 skill, reached from the checklist question that names it; take none60 of them from memory. A red flag alone is a question to the author61 until it has the evidence the index asks for: a measurement, a62 reproducible bug or a failing test.63643. Rule. **Weigh a finding by the label of the rule it breaks.** The65 index defines the three labels under how strictly a rule is meant. A66 broken rule labelled `Rule.` blocks the merge. A broken `Default.`67 blocks unless the change shows that the rule's exception holds. A68 `Judgement.` is discussed, and the author's reasoned choice stands.69 A preference that no rule backs, such as a name the reviewer likes70 better, never blocks.71724. Rule. **Use the diff checklist for a change to existing code, and73 the design checklist for a new module, context or system before its74 code is written.** Each question in them names the rule that75 answers it, and a finding cites that rule, not the checklist.76775. Default. **Ask for the smallest change that keeps the broken rule,78 within the lines the change touches.** Write a finding about code79 the change does not touch as a separate note for later work.8081 The exception is a defect the change makes worse, such as a second82 caller added to a method that already breaks a rule: it is a finding83 against this change.84856. Rule. **Review the tests in a change as part of its design.** Each86 rule the change adds has a test named for that rule that goes87 through the object's public messages, as88 [testing object-oriented code](../oo-testing-object-oriented-code/SKILL.md)89 rules 1 and 3 ask. A rule the change adds with no test at all is a90 finding against that skill's rule 2, which writes each test before91 its code.9293## Pattern9495Before, the change under review adds `attendeeList`, a query that96returns the list the class keeps. `enrol` was there before the change,97so the only line the change adds is `attendeeList`.9899Before:100101```text102class AntenatalClass103 - attendees: List<PatientId>104 + new()105 attendees := new List<PatientId>()106 + enrol(patient: PatientId): void107 attendees.add(patient)108 return109 + attendeeList(): List<PatientId>110 return attendees111```112113After, the change once its one blocking finding is fixed returns a114read-only view. The field, constructor and `enrol` are unchanged.115116After:117118```text119class AntenatalClass120 - attendees: List<PatientId>121 + new()122 attendees := new List<PatientId>()123 + enrol(patient: PatientId): void124 attendees.add(patient)125 return126 + attendeeList(): ReadOnlyList<PatientId>127 return attendees.readOnlyView()128```129130The review has three findings. First, `attendeeList` hands out the list131the class keeps, so a caller can add a patient without `enrol`; that132breaks133[encapsulating state and behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)134rule 5, labelled `Rule.`, so it blocks, under rules 2 and 3. Second, a135wish to call the method `bookedMothers` has no rule behind it, since136`attendeeList` already names the answer as137[naming classes and methods](../oo-naming-classes-and-methods/SKILL.md)138rule 2 asks, so it does not block, under rule 3. Third, `enrol`139accepting the same patient twice lies in code the change does not140touch, so it becomes a separate note, under rule 5.141142`new List<PatientId>()` is taken to mean an empty list the class owns.143Both fences store nothing and leave out how the class is stored. Each144version sets `attendees` in its constructor before `enrol` or145`attendeeList` reads it.146147## Red flags148149Places to look, not verdicts. A red flag becomes a finding only with150evidence: a measurement, a reproducible bug, or a failing test.151152- A review comment with no rule and no evidence behind it.153- A blocking comment on a choice a `Judgement.` rule leaves open.154- A request to change code the change does not touch.155- A new rule in the change with no test named for it.156- A review of a one-method change that asks for a new model.157- A long list of comments with nothing marked as blocking or not.158159## Common mistakes160161- Blocking on a name the reviewer would have chosen.162- Letting a broken `Rule.` pass because the change is small.163- Reviewing the whole module instead of the change.164- Reporting red flags as findings with no evidence.165- Asking for a redesign where a one-line fix keeps the rule.166167## Related skills168169- [oo-design](../oo-design/SKILL.md) sizes a task, defines the rule170 labels, and gives the design loop.171- [oo-recognising-antipatterns](../oo-recognising-antipatterns/SKILL.md)172 names a bad shape and decides what to do about it.173- [oo-testing-object-oriented-code](../oo-testing-object-oriented-code/SKILL.md)174 shapes the tests a change carries.175- [oo-designing-for-testability](../oo-designing-for-testability/SKILL.md)176 moves a value a test cannot repeat behind a port.177- [oo-refactoring-toward-object-design](../oo-refactoring-toward-object-design/SKILL.md)178 restructures code in steps that keep its tests passing.179- [oo-working-with-legacy-code](../oo-working-with-legacy-code/SKILL.md)180 brings old code that no test can build under test first.181182## Further reading183184- [Diff checklist](references/diff-checklist.md)185- [Design checklist](references/design-checklist.md)