Working Within a Framework
In this pack:
sizing,
notation,
rule strictness.
Overview
A framework offers places for code: a base class its mapper saves, a
hook before each save, a setter its binder fills, a marker its container
reads. Each offer is convenient, and none of them is a home for a
business rule. This skill keeps every rule and invariant in the domain,
meets the framework in a class at the edge that converts once, weighs
the demands rule 2 leaves open by whether they reach a rule, and records
each choice once for the code base. Where the framework is built of
functions and components, the clinic's rules still get a module of their
own.
When to use
- A framework asks the clinic's domain classes to extend its base class.
- A form binder wants a setter for each field, or a container wants to
build an object the domain owns.
- A rule sits in a controller, a save hook, a callback or a validation
marker.
- The team is deciding how far to follow a framework, and where to stop.
- The same framework demand is met a different way in two modules.
- A framework built of functions and components holds clinic rules.
When not to use
- The part being changed uses no framework type, such as a domain module
that imports nothing from the framework: the other skills apply
directly.
- The question is only whether one module uses active records or a data
mapper: that is
taming persistence.
- The question is how a screen's state and its logic are split from the
domain: that is
separating presentation from domain.
- The question is how one named framework's own features are called and
configured: outside this skill.
Core rules
Rule. Keep every business rule and every invariant in the domain,
whatever place the framework offers for it: no rule moves into a
controller, a save hook, a callback or a validation marker, and no
domain object can be stored in a state the clinic forbids. A place
the framework offers is still a place in the code, not a licence to
break a rule. The index's labels settle what that costs: no framework
excuses a rule labelled Rule., as
how strictly a rule is meant
says.
Default. Meet a framework's demand in a class at the edge that the
framework shapes, such as a form object, a mapped row or a request
handler, and convert it to the domain's types in one place there.
Deciding object or data
rule 3 converts a transfer object once, and
placing domain logic rule 5
turns text into values at the edge and leaves what is allowed to the
domain. Where a mapper cannot rebuild a domain class through the
class's own factory, it maps a separate stored record and the adapter
converts that, as
taming persistence rule 2 asks.
The exception is a module that
taming persistence rule 1 puts
on active records, because its classes mirror their tables and hold
few rules: there the framework's class is the module's class.
Judgement. Weigh each demand rule 2 does not settle by what it
would cost the domain. Rule 2 settles where a framework base class
goes. When a class holds rules, the base class goes on a class at
the edge, unless taming persistence rule 1 puts the module on active
records: there the module's own classes hold few rules and carry it.
Rule 3 does not weigh that choice again. The demand for a base class
on a mapped row, and the demand for a marker on a request handler,
are met in an edge class rule 2 names, so rule 3 does not weigh them
either. For the demands left, accept one that touches only the edge:
a container that builds the objects the framework builds, as
patterns the language provides
rule 6 allows. Refuse a demand that moves a rule out of the domain,
lets an object exist in a state the clinic forbids, hands a container
to domain code, which
inverting dependencies rule
5 forbids, or leaves a domain method working only while the
framework's session is open, which
taming persistence rule 5
forbids. What tips the balance is whether the demand reaches a rule
or a domain object's messages: going along costs one conversion at
the edge, while fighting the framework where nothing in the domain is
at stake costs code that every later change must carry.
Default. Decide once for the whole code base how it meets each
framework demand, write that one decision down as a decision record,
as documenting design decisions, rule 1, asks of a choice that is
costly to reverse, and meet the demand the same way in every module.
Once means once for the code base, not once for each module: rule 2's
exception for a module on active records is part of that same
decision, so which modules it covers is settled there, not by a
second choice in each module. A second module that meets the same
demand another way is a second design that every later reader must
learn.
The exception is a demand that only one module meets, such as the
scheduler that only the reminders module uses: decide it in that
module.
Default. In a framework built of functions and components rather
than classes, keep the clinic's rules in a module of their own that
the components call, and write that module in the idiom the code
around it uses, as patterns the language provides, rule 7, asks:
never force classes into code built of functions. The module
imports nothing from the framework, so a test calls it with plain
values and no screen. Where the code base is built of functions, the
module is built of functions over values too.
The exception is screen logic, such as which button is enabled, which
separating presentation from domain
rule 2 keeps in what holds the screen's state, where a test can drive
it, rather than in the domain.
Pattern
HomeReading is one blood-pressure reading a patient takes at home.
FrameworkRecord is taken to be the framework's base class for the
objects its mapper saves, and it sends beforeSave to the object before
each save.
Before:
class HomeReading extends FrameworkRecord
- patient: PatientId
- pressure: BloodPressure
- flagged: Boolean
+ new(patient: PatientId, pressure: BloodPressure)
flagged := false
+ beforeSave(): void
if pressure.isHigh() then
flagged := true
+ needsReview(): Boolean
return flagged
In the Before, the rule that a high reading needs review lives in that
hook, so needsReview() answers false for a high reading until the
framework saves it, and a reading stored by any path that skips the hook
is never flagged (rule 1).
After:
class HomeReading
- patient: PatientId
- pressure: BloodPressure
+ new(patient: PatientId, pressure: BloodPressure)
+ needsReview(): Boolean
return pressure.isHigh()
In the After, needsReview() keeps the rule from the moment the reading
is built, and HomeReading extends nothing of the framework. The
framework's base class goes on a row class at the edge, converted to and
from HomeReading in one adapter, as
taming persistence rule 2 keeps
every mapping decision there; the row class and the adapter are left out
of the fence (rule 2).
The base class on the row is the edge class rule 2 asks for, and the
hook is refused because it reaches a rule (rule 3).
BloodPressure is taken to be a value whose isHigh() answers whether
the reading is above the clinic's level for review. true and false
are the two values a Boolean holds. patient is set by the constructor
and read by neither fence.
The fences store nothing, and the use case that stores a reading through
its repository, in the transaction it opens and ends, is left out. In the
Before, flagged is set before needsReview reads it; in the After,
needsReview reads only the fields its constructor set.
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 business rule in a save hook, a callback or a controller.
- A domain class that extends a framework's base class or carries its
markers.
- A domain class that asks a container for a collaborator.
- A domain method that fails once the framework's session has closed.
- The same framework demand met a different way in each module.
- Classes written into a module whose code is built of functions.
Common mistakes
- Moving a rule into the place the framework offers because the place
is there.
- Wrapping every framework call in an interface of the team's own when
no rule is at stake.
- Letting a form binder fill domain objects field by field.
- Deciding the same framework demand again in every pull request.
- Rewriting screen code built of functions into classes.
Related skills
- oo-design
sizes a task and defines the three rule labels.
- oo-taming-persistence
rules 1, 2 and 5, for active records, the adapter's mapping and lazy
loading.
- oo-inverting-dependencies
rule 5, and rule 4's exception, for a container and the composition
root.
- oo-deciding-object-or-data
rule 3, for a transfer object converted once at the edge.
- oo-placing-domain-logic
rule 5, for well-formed input at the edge and the allowed decision in
the domain.
- oo-separating-presentation-from-domain
rule 2, for screen state and screen logic in a presentation object.
- oo-patterns-the-language-provides
rules 6 and 7, for a container where a framework builds objects and
for following the code's idiom.
- oo-documenting-design-decisions
rule 1, for a record of a choice that is costly to reverse.
Further reading
- Framework pressures
- When the framework is not object-oriented
1---2name: oo-working-within-a-framework3description: Use when a framework wants domain classes to extend its base class, offer setters or carry its markers, or deciding how far to go along with it.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-working-within-a-framework7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Working Within a Framework1213**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 framework offers places for code: a base class its mapper saves, a21hook before each save, a setter its binder fills, a marker its container22reads. Each offer is convenient, and none of them is a home for a23business rule. This skill keeps every rule and invariant in the domain,24meets the framework in a class at the edge that converts once, weighs25the demands rule 2 leaves open by whether they reach a rule, and records26each choice once for the code base. Where the framework is built of27functions and components, the clinic's rules still get a module of their28own.2930## When to use3132- A framework asks the clinic's domain classes to extend its base class.33- A form binder wants a setter for each field, or a container wants to34 build an object the domain owns.35- A rule sits in a controller, a save hook, a callback or a validation36 marker.37- The team is deciding how far to follow a framework, and where to stop.38- The same framework demand is met a different way in two modules.39- A framework built of functions and components holds clinic rules.4041## When not to use4243- The part being changed uses no framework type, such as a domain module44 that imports nothing from the framework: the other skills apply45 directly.46- The question is only whether one module uses active records or a data47 mapper: that is48 [taming persistence](../oo-taming-persistence/SKILL.md).49- The question is how a screen's state and its logic are split from the50 domain: that is51 [separating presentation from domain](../oo-separating-presentation-from-domain/SKILL.md).52- The question is how one named framework's own features are called and53 configured: outside this skill.5455## Core rules56571. Rule. **Keep every business rule and every invariant in the domain,58 whatever place the framework offers for it: no rule moves into a59 controller, a save hook, a callback or a validation marker, and no60 domain object can be stored in a state the clinic forbids.** A place61 the framework offers is still a place in the code, not a licence to62 break a rule. The index's labels settle what that costs: no framework63 excuses a rule labelled `Rule.`, as64 [how strictly a rule is meant](../oo-design/SKILL.md#how-strictly-a-rule-is-meant)65 says.66672. Default. **Meet a framework's demand in a class at the edge that the68 framework shapes, such as a form object, a mapped row or a request69 handler, and convert it to the domain's types in one place there.**70 [Deciding object or data](../oo-deciding-object-or-data/SKILL.md)71 rule 3 converts a transfer object once, and72 [placing domain logic](../oo-placing-domain-logic/SKILL.md) rule 573 turns text into values at the edge and leaves what is allowed to the74 domain. Where a mapper cannot rebuild a domain class through the75 class's own factory, it maps a separate stored record and the adapter76 converts that, as77 [taming persistence](../oo-taming-persistence/SKILL.md) rule 2 asks.78 The exception is a module that79 [taming persistence](../oo-taming-persistence/SKILL.md) rule 1 puts80 on active records, because its classes mirror their tables and hold81 few rules: there the framework's class is the module's class.82833. Judgement. **Weigh each demand rule 2 does not settle by what it84 would cost the domain.** Rule 2 settles where a framework base class85 goes. When a class holds rules, the base class goes on a class at86 the edge, unless taming persistence rule 1 puts the module on active87 records: there the module's own classes hold few rules and carry it.88 Rule 3 does not weigh that choice again. The demand for a base class89 on a mapped row, and the demand for a marker on a request handler,90 are met in an edge class rule 2 names, so rule 3 does not weigh them91 either. For the demands left, accept one that touches only the edge:92 a container that builds the objects the framework builds, as93 [patterns the language provides](../oo-patterns-the-language-provides/SKILL.md)94 rule 6 allows. Refuse a demand that moves a rule out of the domain,95 lets an object exist in a state the clinic forbids, hands a container96 to domain code, which97 [inverting dependencies](../oo-inverting-dependencies/SKILL.md) rule98 5 forbids, or leaves a domain method working only while the99 framework's session is open, which100 [taming persistence](../oo-taming-persistence/SKILL.md) rule 5101 forbids. What tips the balance is whether the demand reaches a rule102 or a domain object's messages: going along costs one conversion at103 the edge, while fighting the framework where nothing in the domain is104 at stake costs code that every later change must carry.1051064. Default. **Decide once for the whole code base how it meets each107 framework demand, write that one decision down as a decision record,108 as documenting design decisions, rule 1, asks of a choice that is109 costly to reverse, and meet the demand the same way in every module.**110 Once means once for the code base, not once for each module: rule 2's111 exception for a module on active records is part of that same112 decision, so which modules it covers is settled there, not by a113 second choice in each module. A second module that meets the same114 demand another way is a second design that every later reader must115 learn.116 The exception is a demand that only one module meets, such as the117 scheduler that only the reminders module uses: decide it in that118 module.1191205. Default. **In a framework built of functions and components rather121 than classes, keep the clinic's rules in a module of their own that122 the components call, and write that module in the idiom the code123 around it uses, as patterns the language provides, rule 7, asks:124 never force classes into code built of functions.** The module125 imports nothing from the framework, so a test calls it with plain126 values and no screen. Where the code base is built of functions, the127 module is built of functions over values too.128 The exception is screen logic, such as which button is enabled, which129 [separating presentation from domain](../oo-separating-presentation-from-domain/SKILL.md)130 rule 2 keeps in what holds the screen's state, where a test can drive131 it, rather than in the domain.132133## Pattern134135`HomeReading` is one blood-pressure reading a patient takes at home.136`FrameworkRecord` is taken to be the framework's base class for the137objects its mapper saves, and it sends `beforeSave` to the object before138each save.139140Before:141142```text143class HomeReading extends FrameworkRecord144 - patient: PatientId145 - pressure: BloodPressure146 - flagged: Boolean147 + new(patient: PatientId, pressure: BloodPressure)148 flagged := false149 + beforeSave(): void150 if pressure.isHigh() then151 flagged := true152 + needsReview(): Boolean153 return flagged154```155156In the Before, the rule that a high reading needs review lives in that157hook, so `needsReview()` answers `false` for a high reading until the158framework saves it, and a reading stored by any path that skips the hook159is never flagged (rule 1).160161After:162163```text164class HomeReading165 - patient: PatientId166 - pressure: BloodPressure167 + new(patient: PatientId, pressure: BloodPressure)168 + needsReview(): Boolean169 return pressure.isHigh()170```171172In the After, `needsReview()` keeps the rule from the moment the reading173is built, and `HomeReading` extends nothing of the framework. The174framework's base class goes on a row class at the edge, converted to and175from `HomeReading` in one adapter, as176[taming persistence](../oo-taming-persistence/SKILL.md) rule 2 keeps177every mapping decision there; the row class and the adapter are left out178of the fence (rule 2).179The base class on the row is the edge class rule 2 asks for, and the180hook is refused because it reaches a rule (rule 3).181182`BloodPressure` is taken to be a value whose `isHigh()` answers whether183the reading is above the clinic's level for review. `true` and `false`184are the two values a `Boolean` holds. `patient` is set by the constructor185and read by neither fence.186187The fences store nothing, and the use case that stores a reading through188its repository, in the transaction it opens and ends, is left out. In the189Before, `flagged` is set before `needsReview` reads it; in the After,190`needsReview` reads only the fields its constructor set.191192## Red flags193194Places to look, not verdicts. A red flag becomes a finding only with195evidence: a measurement, a reproducible bug, or a failing test.196197- A business rule in a save hook, a callback or a controller.198- A domain class that extends a framework's base class or carries its199 markers.200- A domain class that asks a container for a collaborator.201- A domain method that fails once the framework's session has closed.202- The same framework demand met a different way in each module.203- Classes written into a module whose code is built of functions.204205## Common mistakes206207- Moving a rule into the place the framework offers because the place208 is there.209- Wrapping every framework call in an interface of the team's own when210 no rule is at stake.211- Letting a form binder fill domain objects field by field.212- Deciding the same framework demand again in every pull request.213- Rewriting screen code built of functions into classes.214215## Related skills216217- [oo-design](../oo-design/SKILL.md)218 sizes a task and defines the three rule labels.219- [oo-taming-persistence](../oo-taming-persistence/SKILL.md)220 rules 1, 2 and 5, for active records, the adapter's mapping and lazy221 loading.222- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)223 rule 5, and rule 4's exception, for a container and the composition224 root.225- [oo-deciding-object-or-data](../oo-deciding-object-or-data/SKILL.md)226 rule 3, for a transfer object converted once at the edge.227- [oo-placing-domain-logic](../oo-placing-domain-logic/SKILL.md)228 rule 5, for well-formed input at the edge and the allowed decision in229 the domain.230- [oo-separating-presentation-from-domain](../oo-separating-presentation-from-domain/SKILL.md)231 rule 2, for screen state and screen logic in a presentation object.232- [oo-patterns-the-language-provides](../oo-patterns-the-language-provides/SKILL.md)233 rules 6 and 7, for a container where a framework builds objects and234 for following the code's idiom.235- [oo-documenting-design-decisions](../oo-documenting-design-decisions/SKILL.md)236 rule 1, for a record of a choice that is costly to reverse.237238## Further reading239240- [Framework pressures](references/pressures.md)241- [When the framework is not object-oriented](references/not-object-oriented.md)