Speaking the Domain Language
In this pack:
sizing,
notation,
rule strictness.
Overview
The words in the code are the words the staff will use when they talk
about the code. When the two vocabularies drift apart, every
conversation needs a translation and every rule needs a comment. This
skill keeps one vocabulary: classes, methods and events take the words
the people who do the work already use, a concept they rely on gets a
type or a method of its own, and a word with two meanings becomes two
concepts. It also keeps the vocabulary of storage, transport and
frameworks outside the domain model.
Choosing the grammar of a name is a separate question, and this skill
leaves it to naming classes and methods. The aim here is the word, not
its form.
When to use
- Reception, nursing or billing uses a word the code spells differently.
- The staff describe a step or a thing that no class or method models.
- Two teams use one word for different things.
- A field's meaning depends on a comment, a status number or a flag.
- A domain class carries a storage or framework word in its name.
When not to use
- The only question is how to phrase a name, such as a noun for a class,
a verb for a command or a Manager suffix, and no domain word is in
dispute: that is naming classes and methods.
- The code is already split into separately owned parts, each with its
own model, and the question is where the line between them runs or how
they translate at it.
- The words come from an outside standard the code must match, such as
the field names of a message format or a coding scheme the clinic does
not own.
Core rules
Rule. Name a class, a method or an event with the same word the
people who do the work use for it. If reception says a patient
checks in, the code says checkIn; if the nurses say a patient
missed an appointment, the code says recordNoShow, not
updateState(2) or flagAbsent. Code that needs a translation table
before it can be discussed with the staff is where misunderstandings
hide. Whether a name should be a noun for a class or a verb for a
command is a question for rules 1 and 2 of naming classes and
methods.
Default. When the staff talk about something the code has no class
or method for, give it one. A recall that lives only as a flag, a
date field and a comment becomes a type or a method with that name,
holding its own rule; a double booking stored the same way becomes
the operation that refuses the second booking. The staff use the word
because they decide something with it, and code that stores the
pieces without the concept leaves that decision scattered.
The exception is a word that names nothing the code decides on, such
as a label printed on a report: it stays data.
Judgement. Find the words by walking through the work with the
people who do it, one event at a time. This is event storming:
write down what happens, in the past tense (appointment booked,
patient checked in), then the request that causes each event, who
makes it, and the rule that can refuse it. Each event, request and
rule is a candidate name for an event, a method and a check in the
code. What tips the balance is how much of the process the team
cannot yet name: a walkthrough pays off for a new or disputed
process, while for a small change the staff's own forms and messages
give the words.
Rule. When two groups use one word for two different things, keep
two concepts in the code. Never let one class serve both meanings
through flags or optional fields: to reception an appointment is a
booked slot, while to billing it is a billable visit. Where the two
meanings share code, each gets its own word, as rule 4 of naming
classes and methods describes. Where each group's code is already
separate, bounding contexts draws
the line between them.
Default. When the code's word for a thing differs from the staff's,
change the code to the staff's word in the change that finds the
difference. Use that word in tests and in the team's talk too, so
one vocabulary covers both the work and the code; a name other
systems depend on keeps the exception to rule 6 of naming classes and
methods.
The exception is a word the staff themselves use vaguely or for two
things: agree a sharper word with them, write it down beside the
code, and use that one everywhere.
Rule. Keep storage, transport and framework words out of the domain
model. PatientDto, AppointmentEntity, SlotRow and
BookingJson belong at the edge that talks to that storage or
framework, while the domain classes are Patient, Appointment and
Slot. The class at that edge takes the outside system's name, as
rule 3 of naming classes and methods allows for an adapter. A
technical word inside the model hides the staff's words and ties the
model to one way of storing it.
Pattern
Before, FollowUpTask holds the recall as a boolean flag and a comment
explains what the flag means. After, Recall names the concept, its
fields say what it holds, and booking an appointment is an action it
refuses a second time.
Before:
class FollowUpTask
- patient: PatientId
- due: Date
- flag: Boolean
-- the flag means the recall has been booked
+ new(patient: PatientId, due: Date)
flag := false
+ update(): void
flag := true
After:
class Recall
- patient: PatientId
- dueOn: Date
- booking: AppointmentId?
+ new(patient: PatientId, dueOn: Date)
booking := null
+ book(appointment: AppointmentId): void
raises RecallAlreadyBooked
if booking = null then
booking := appointment
else
raise RecallAlreadyBooked
return
true and false are taken to mean the two values a Boolean can
hold, and null is the absent value of an optional field.
FollowUpTask's constructor sets flag once, and update sets it
once; patient and due come from the constructor's parameters.
Recall's constructor sets booking once, and book reads it once
and sets it once when it is empty. RecallAlreadyBooked is raised the
way Slot.reserve raises SlotTaken in the notation. No field is read
before it is set, and no step runs twice.
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 class, method or field name the staff would not recognise for a
thing they talk about every day.
- A status number or code, such as
status = 4, that people translate
into a word in meetings.
- A comment that explains in the staff's words what a field means.
- One class with fields or flags that only one team ever reads.
- A storage or framework word, such as Dto, Entity, Row or Json, in a
domain class's name.
Common mistakes
- Inventing a technical word for a concept the staff already have a word
for.
- Merging two teams' meanings of one word into one class with a flag for
each.
- Agreeing a new word with the staff and leaving the code on the old
one.
- Keeping a glossary the code no longer matches.
- Copying the staff's word for something that is really two things,
without asking which one they mean.
Related skills
Further reading
- Walking through the work
- Two meanings of one word
1---2name: oo-speaking-the-domain-language3description: Use when code words differ from what staff say, when staff talk about something no class models, or two teams mean different things by one word.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-speaking-the-domain-language7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Speaking the Domain Language1213**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## Overview1920The words in the code are the words the staff will use when they talk21about the code. When the two vocabularies drift apart, every22conversation needs a translation and every rule needs a comment. This23skill keeps one vocabulary: classes, methods and events take the words24the people who do the work already use, a concept they rely on gets a25type or a method of its own, and a word with two meanings becomes two26concepts. It also keeps the vocabulary of storage, transport and27frameworks outside the domain model.2829Choosing the grammar of a name is a separate question, and this skill30leaves it to naming classes and methods. The aim here is the word, not31its form.3233## When to use3435- Reception, nursing or billing uses a word the code spells differently.36- The staff describe a step or a thing that no class or method models.37- Two teams use one word for different things.38- A field's meaning depends on a comment, a status number or a flag.39- A domain class carries a storage or framework word in its name.4041## When not to use4243- The only question is how to phrase a name, such as a noun for a class,44 a verb for a command or a Manager suffix, and no domain word is in45 dispute: that is naming classes and methods.46- The code is already split into separately owned parts, each with its47 own model, and the question is where the line between them runs or how48 they translate at it.49- The words come from an outside standard the code must match, such as50 the field names of a message format or a coding scheme the clinic does51 not own.5253## Core rules54551. Rule. **Name a class, a method or an event with the same word the56 people who do the work use for it.** If reception says a patient57 *checks in*, the code says `checkIn`; if the nurses say a patient58 *missed* an appointment, the code says `recordNoShow`, not59 `updateState(2)` or `flagAbsent`. Code that needs a translation table60 before it can be discussed with the staff is where misunderstandings61 hide. Whether a name should be a noun for a class or a verb for a62 command is a question for rules 1 and 2 of naming classes and63 methods.64652. Default. **When the staff talk about something the code has no class66 or method for, give it one.** A *recall* that lives only as a flag, a67 date field and a comment becomes a type or a method with that name,68 holding its own rule; a *double booking* stored the same way becomes69 the operation that refuses the second booking. The staff use the word70 because they decide something with it, and code that stores the71 pieces without the concept leaves that decision scattered.7273 The exception is a word that names nothing the code decides on, such74 as a label printed on a report: it stays data.75763. Judgement. **Find the words by walking through the work with the77 people who do it, one event at a time.** This is event storming:78 write down what happens, in the past tense (*appointment booked*,79 *patient checked in*), then the request that causes each event, who80 makes it, and the rule that can refuse it. Each event, request and81 rule is a candidate name for an event, a method and a check in the82 code. What tips the balance is how much of the process the team83 cannot yet name: a walkthrough pays off for a new or disputed84 process, while for a small change the staff's own forms and messages85 give the words.86874. Rule. **When two groups use one word for two different things, keep88 two concepts in the code.** Never let one class serve both meanings89 through flags or optional fields: to reception an *appointment* is a90 booked slot, while to billing it is a billable visit. Where the two91 meanings share code, each gets its own word, as rule 4 of naming92 classes and methods describes. Where each group's code is already93 separate, [bounding contexts](../oo-bounding-contexts/SKILL.md) draws94 the line between them.95965. Default. **When the code's word for a thing differs from the staff's,97 change the code to the staff's word in the change that finds the98 difference.** Use that word in tests and in the team's talk too, so99 one vocabulary covers both the work and the code; a name other100 systems depend on keeps the exception to rule 6 of naming classes and101 methods.102103 The exception is a word the staff themselves use vaguely or for two104 things: agree a sharper word with them, write it down beside the105 code, and use that one everywhere.1061076. Rule. **Keep storage, transport and framework words out of the domain108 model.** `PatientDto`, `AppointmentEntity`, `SlotRow` and109 `BookingJson` belong at the edge that talks to that storage or110 framework, while the domain classes are `Patient`, `Appointment` and111 `Slot`. The class at that edge takes the outside system's name, as112 rule 3 of naming classes and methods allows for an adapter. A113 technical word inside the model hides the staff's words and ties the114 model to one way of storing it.115116## Pattern117118Before, `FollowUpTask` holds the recall as a boolean flag and a comment119explains what the flag means. After, `Recall` names the concept, its120fields say what it holds, and booking an appointment is an action it121refuses a second time.122123Before:124125```text126class FollowUpTask127 - patient: PatientId128 - due: Date129 - flag: Boolean130 -- the flag means the recall has been booked131 + new(patient: PatientId, due: Date)132 flag := false133 + update(): void134 flag := true135```136137After:138139```text140class Recall141 - patient: PatientId142 - dueOn: Date143 - booking: AppointmentId?144 + new(patient: PatientId, dueOn: Date)145 booking := null146 + book(appointment: AppointmentId): void147 raises RecallAlreadyBooked148 if booking = null then149 booking := appointment150 else151 raise RecallAlreadyBooked152 return153```154155`true` and `false` are taken to mean the two values a `Boolean` can156hold, and `null` is the absent value of an optional field.157`FollowUpTask`'s constructor sets `flag` once, and `update` sets it158once; `patient` and `due` come from the constructor's parameters.159`Recall`'s constructor sets `booking` once, and `book` reads it once160and sets it once when it is empty. `RecallAlreadyBooked` is raised the161way `Slot.reserve` raises `SlotTaken` in the notation. No field is read162before it is set, and no step runs twice.163164## Red flags165166Places to look, not verdicts. A red flag becomes a finding only with167evidence: a measurement, a reproducible bug, or a failing test.168169- A class, method or field name the staff would not recognise for a170 thing they talk about every day.171- A status number or code, such as `status = 4`, that people translate172 into a word in meetings.173- A comment that explains in the staff's words what a field means.174- One class with fields or flags that only one team ever reads.175- A storage or framework word, such as Dto, Entity, Row or Json, in a176 domain class's name.177178## Common mistakes179180- Inventing a technical word for a concept the staff already have a word181 for.182- Merging two teams' meanings of one word into one class with a flag for183 each.184- Agreeing a new word with the staff and leaving the code on the old185 one.186- Keeping a glossary the code no longer matches.187- Copying the staff's word for something that is really two things,188 without asking which one they mean.189190## Related skills191192- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule193 labels.194- [oo-naming-classes-and-methods](../oo-naming-classes-and-methods/SKILL.md)195 chooses the grammar of a name and keeps one word for one concept.196- [oo-assigning-responsibilities](../oo-assigning-responsibilities/SKILL.md)197 finds the owner of a concept once the concept has a name.198- [oo-bounding-contexts](../oo-bounding-contexts/SKILL.md) draws the199 line between separately owned models.200201## Further reading202203- [Walking through the work](references/walking-through-the-work.md)204- [Two meanings of one word](references/two-meanings-of-one-word.md)