Naming Classes and Methods
In this pack:
sizing,
notation,
rule strictness.
Overview
A name is the shortest description of a piece of code, and every reader
pays for it again at each call. This skill chooses names that say what an
object is, what a command does and what a query answers. It keeps one
word for one concept and moves a name in the same change that moves its
meaning. It does not choose the clinic's words for a concept; it makes
the chosen words honest and consistent.
When to use
- A new class or method needs a name.
- A name ends in Manager, Helper, Util, Processor or Data, or a method
is called
process or handle.
- A reader cannot tell what a method returns or what a class holds.
- Two words describe the same concept in nearby code.
- A name still describes the old behaviour after a change.
When not to use
- The class does several unrelated jobs and no honest name fits it:
split it first, as
assigning responsibilities
describes.
- The question is which words the clinic's staff use for a concept, or
two teams use one word for different things: that is a question of the
domain's language, not of naming grammar.
- The name is fixed by a framework or a protocol, such as a lifecycle
method the framework calls or a field a message format requires.
- The spelling or prefix is fixed by the language or its tools, such as
the form an accessor must take. The language pack carries that
convention.
Core rules
Rule. Name a class for what each instance is, or for the one job it
does, as a noun phrase. Slot, WaitingList and RoomPlanner say
what an instance is or the job it owns. When the only name that fits
ends in Manager, Helper, Util, Processor or Data, the class has no
single job yet: find its job first, as
assigning responsibilities
describes, and the name follows.
Rule. Name a command for the effect it has, as a verb phrase, and a
query for the answer it gives, as a noun phrase or a yes-or-no
question. reserve, cancel and register name effects;
startsAt, fee and isFree name answers. A query's name on a
method that changes state misleads every caller; whether such a
method is split follows rule 4 of
encapsulating state and behaviour,
including its exception for returning what was just created. An
operation on an immutable value that returns the changed copy may
take the verb of the change it models, such as plus, because it
changes nothing.
Default. Name for what the code means to its callers, not for how
it works inside. waiting() says what a caller learns, where
patientList() says how the answer is stored. freeSlots(date) says
what a caller may do with the answer, where slotsWithNoPatient(date)
says how the code decides.
The exception is a class whose job is the mechanism itself, such as
an adapter for an outside system: the outside system's name is its
meaning.
Rule. Use one word for one concept throughout the code, and
different words for different concepts. If one class says cancel,
no sibling says revoke for the same act, and slot never also
means a room. A reader who learns a word once can trust it everywhere.
The rule holds inside one model; separately owned contexts may each
give one word a meaning of their own, as
bounding contexts describes.
Judgement. Match a name's length to how far from its declaration it
is read. A two-line local may be short, while a public class or
method read across the code needs a name that stands alone. What tips
the balance is whether a reader at the farthest use can tell what the
name holds without opening its declaration.
Default. Rename in the same change that changes a name's
meaning. A name that no longer says what the code does costs every
later reader, and a comment explaining the gap is the sign. The change
that widens the behaviour carries the rename, so no revision shows the
old name on the new behaviour.
The exception is a name other systems depend on, such as a published
interface or a stored code: add the new name beside the old one and
retire the old one on a schedule.
Pattern
Before, every name in PatientHelper describes a mechanism rather than
a register of patients. After, the same class is PatientRegister, with
method and parameter names that say what each one means. Only names
change: the field still holds a List<Patient>, the constructor still
creates an empty list, and each method sends the same message and
returns the same kind of result.
Before:
class PatientHelper
- items: List<Patient>
+ new()
items := new List<Patient>()
+ add(x: Patient): void
items.add(x)
return
+ lookup(x: Patient): Boolean
return items.contains(x)
After:
class PatientRegister
- patients: List<Patient>
+ new()
patients := new List<Patient>()
+ register(patient: Patient): void
patients.add(patient)
return
+ isRegistered(patient: Patient): Boolean
return patients.contains(patient)
add and register each send add to the field once. lookup and
isRegistered each send contains to the field once and change
nothing. The constructor sets the field before any read, and the list
stays private, so no caller receives 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 class name ending in Manager, Helper, Util, Processor, Handler or
Data.
- A method called
process, handle, execute or perform on a class
with more than one job.
- A method whose name reads as a query, such as
get... or is..., but
which changes state.
- A boolean parameter that switches a method between two behaviours.
- Two words for one concept in the same code, or one word for two
concepts.
- A comment that says what a name should have said.
Common mistakes
- Renaming a Manager to a Service and keeping all its jobs.
- Putting the type or the storage in a name, such as
patientList or
slotMap.
- Shortening a public name to save typing.
- Naming a class for the pattern it uses when its callers only need its
job.
- Keeping a name after its meaning changed and explaining the gap in a
comment.
Related skills
Further reading
- Names that mislead
- Vague words
1---2name: oo-naming-classes-and-methods3description: Use when choosing what to call a class or method, when names end in Manager, Helper or Util, or when a name no longer says what the code does.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-naming-classes-and-methods7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Naming Classes and Methods1213**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 name is the shortest description of a piece of code, and every reader21pays for it again at each call. This skill chooses names that say what an22object is, what a command does and what a query answers. It keeps one23word for one concept and moves a name in the same change that moves its24meaning. It does not choose the clinic's words for a concept; it makes25the chosen words honest and consistent.2627## When to use2829- A new class or method needs a name.30- A name ends in Manager, Helper, Util, Processor or Data, or a method31 is called `process` or `handle`.32- A reader cannot tell what a method returns or what a class holds.33- Two words describe the same concept in nearby code.34- A name still describes the old behaviour after a change.3536## When not to use3738- The class does several unrelated jobs and no honest name fits it:39 split it first, as40 [assigning responsibilities](../oo-assigning-responsibilities/SKILL.md)41 describes.42- The question is which words the clinic's staff use for a concept, or43 two teams use one word for different things: that is a question of the44 domain's language, not of naming grammar.45- The name is fixed by a framework or a protocol, such as a lifecycle46 method the framework calls or a field a message format requires.47- The spelling or prefix is fixed by the language or its tools, such as48 the form an accessor must take. The language pack carries that49 convention.5051## Core rules52531. Rule. **Name a class for what each instance is, or for the one job it54 does, as a noun phrase.** `Slot`, `WaitingList` and `RoomPlanner` say55 what an instance is or the job it owns. When the only name that fits56 ends in Manager, Helper, Util, Processor or Data, the class has no57 single job yet: find its job first, as58 [assigning responsibilities](../oo-assigning-responsibilities/SKILL.md)59 describes, and the name follows.60612. Rule. **Name a command for the effect it has, as a verb phrase, and a62 query for the answer it gives, as a noun phrase or a yes-or-no63 question.** `reserve`, `cancel` and `register` name effects;64 `startsAt`, `fee` and `isFree` name answers. A query's name on a65 method that changes state misleads every caller; whether such a66 method is split follows rule 4 of67 [encapsulating state and behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md),68 including its exception for returning what was just created. An69 operation on an immutable value that returns the changed copy may70 take the verb of the change it models, such as `plus`, because it71 changes nothing.72733. Default. **Name for what the code means to its callers, not for how74 it works inside.** `waiting()` says what a caller learns, where75 `patientList()` says how the answer is stored. `freeSlots(date)` says76 what a caller may do with the answer, where `slotsWithNoPatient(date)`77 says how the code decides.7879 The exception is a class whose job is the mechanism itself, such as80 an adapter for an outside system: the outside system's name is its81 meaning.82834. Rule. **Use one word for one concept throughout the code, and84 different words for different concepts.** If one class says `cancel`,85 no sibling says `revoke` for the same act, and `slot` never also86 means a room. A reader who learns a word once can trust it everywhere.87 The rule holds inside one model; separately owned contexts may each88 give one word a meaning of their own, as89 [bounding contexts](../oo-bounding-contexts/SKILL.md) describes.90915. Judgement. **Match a name's length to how far from its declaration it92 is read.** A two-line local may be short, while a public class or93 method read across the code needs a name that stands alone. What tips94 the balance is whether a reader at the farthest use can tell what the95 name holds without opening its declaration.96976. Default. **Rename in the same change that changes a name's98 meaning.** A name that no longer says what the code does costs every99 later reader, and a comment explaining the gap is the sign. The change100 that widens the behaviour carries the rename, so no revision shows the101 old name on the new behaviour.102103 The exception is a name other systems depend on, such as a published104 interface or a stored code: add the new name beside the old one and105 retire the old one on a schedule.106107## Pattern108109Before, every name in `PatientHelper` describes a mechanism rather than110a register of patients. After, the same class is `PatientRegister`, with111method and parameter names that say what each one means. Only names112change: the field still holds a `List<Patient>`, the constructor still113creates an empty list, and each method sends the same message and114returns the same kind of result.115116Before:117118```text119class PatientHelper120 - items: List<Patient>121 + new()122 items := new List<Patient>()123 + add(x: Patient): void124 items.add(x)125 return126 + lookup(x: Patient): Boolean127 return items.contains(x)128```129130After:131132```text133class PatientRegister134 - patients: List<Patient>135 + new()136 patients := new List<Patient>()137 + register(patient: Patient): void138 patients.add(patient)139 return140 + isRegistered(patient: Patient): Boolean141 return patients.contains(patient)142```143144`add` and `register` each send `add` to the field once. `lookup` and145`isRegistered` each send `contains` to the field once and change146nothing. The constructor sets the field before any read, and the list147stays private, so no caller receives it.148149## Red flags150151Places to look, not verdicts. A red flag becomes a finding only with152evidence: a measurement, a reproducible bug, or a failing test.153154- A class name ending in Manager, Helper, Util, Processor, Handler or155 Data.156- A method called `process`, `handle`, `execute` or `perform` on a class157 with more than one job.158- A method whose name reads as a query, such as `get...` or `is...`, but159 which changes state.160- A boolean parameter that switches a method between two behaviours.161- Two words for one concept in the same code, or one word for two162 concepts.163- A comment that says what a name should have said.164165## Common mistakes166167- Renaming a Manager to a Service and keeping all its jobs.168- Putting the type or the storage in a name, such as `patientList` or169 `slotMap`.170- Shortening a public name to save typing.171- Naming a class for the pattern it uses when its callers only need its172 job.173- Keeping a name after its meaning changed and explaining the gap in a174 comment.175176## Related skills177178- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule179 labels.180- [oo-assigning-responsibilities](../oo-assigning-responsibilities/SKILL.md)181 finds the class and the job before its name.182- [oo-encapsulating-state-and-behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)183 keeps a command and a query apart, and keeps a collection private.184- [oo-bounding-contexts](../oo-bounding-contexts/SKILL.md) lets185 separately owned contexts give one word a meaning of their own.186187## Further reading188189- [Names that mislead](references/names-that-mislead.md)190- [Vague words](references/vague-words.md)