Commenting What Code Cannot Say
In this pack:
sizing,
notation,
rule strictness.
Overview
Code carries most of what a reader needs: a name says what a class or
method is for, a value type holds a rule, and a test names a behaviour.
This skill keeps the small remainder honest. It puts a reason, an outside
constraint, a trade-off or a warning in a comment only where no name,
type or test can carry it, deletes the comments that repeat what the code
already says, and treats a comment that disagrees with the code as a
defect in the change that finds it. Every comment it keeps describes the
code as it is now.
When to use
- A comment restates the name or the signature beside it.
- A comment disagrees with the code, and a reader cannot tell which one
is right.
- A comment block lists who changed the code and when, or what it
replaced.
- Code no longer used sits commented out in the file.
- A reader asks why a line takes the longer road, or what limit another
system or organisation sets.
- A comment is about to explain a name that could say the same thing.
- A surprising behaviour needs either a comment or a test.
When not to use
- The question is why a choice that reaches across modules was made, and
where its record lives: that is
documenting design decisions.
- The question is what a class or method should be called: that is
naming classes and methods.
- The question is what a type's contract must promise so that every
subtype keeps it: that is
honouring substitutability.
- The text is for people who do not read the code, such as a guide for
receptionists or the reference of a published interface: outside this
skill.
Core rules
Rule. Say it in the code first, and comment only what is left: a
name that says what a class or method is for, as naming classes and
methods, rules 1 to 3, asks; a value type for a primitive that carries
a rule, as modeling values and entities, rule 5, asks; a method named
for a step that needed a comment; or a test named for a behaviour.
Each of those carries its meaning where a reader meets it, so no
second text has to be kept true. A comment comes after them, and only
for what none of them can hold.
Rule. Comment why, not what: a reason the code cannot show, a
constraint from outside the code, such as what another system accepts,
a trade-off the team chose, or a warning about a consequence a reader
would not expect. A comment that describes the next line competes
with it: a reader follows the note and skips the line, and the note
goes stale when the line changes. Keep the note beside the code it
explains, short enough to read in one pass.
Rule. Treat a comment that disagrees with the code as a defect, and
fix it in the change that finds it: find out which one is right, from
the people who own the rule or from a test, then correct the comment
or the code, and add a test when the code was wrong. Leave neither
the wrong note nor the wrong line for a later change. A note corrected
to match a defect teaches every reader the defect.
Default. Delete a comment that repeats what the code already says,
such as a comment naming the constructor above it. A second copy of
one fact is one more copy to keep true, and it is the copy that drifts
first.
The exception is the contract under a public method's signature,
where honouring substitutability, rule 4, asks for one: callers read
the contract instead of the body, so it stays even where the body
happens to show the same thing.
Rule. Keep history out of comments: who changed a line, when, and
what it replaced belong to version control; a choice's reasons and the
options weighed belong to its decision record, as documenting design
decisions, rule 2, keeps them; and code no longer used is deleted, not
commented out. Read the note as a statement about the code in front
of you, with one line at most naming the record that gives the reasons.
Judgement. Choose between a comment and a test for a behaviour that
would surprise a reader. A test named for the behaviour fails when
the behaviour changes, where a comment stays quiet through the same
change. A comment can still carry a reason no test can show, such as a
limit another organisation sets. What tips the balance is whether a
test can show the behaviour: when it can, write the test, and keep at
most a one-line reason beside the code.
Pattern
HostedVideoRooms is the adapter behind the clinic's VideoRooms port
for telehealth visits, and the one class that knows the provider's
client (crossing system boundaries, rule 3), so the outside constraint
is written here and on no domain class.
Before:
class HostedVideoRooms implements VideoRooms
- provider: VideoProvider
-- the constructor
+ new(provider: VideoProvider)
-- opens one room per patient for the whole day
+ roomFor(visit: VisitId): RoomLink
return RoomLink.at(provider.openRoom(visit.text()))
In the Before, "the constructor" repeats the code beside it (rule 4),
and "one room per patient for the whole day" disagrees with it: roomFor
opens a room for a visit, so the code is right (rule 3).
After:
class HostedVideoRooms implements VideoRooms
- provider: VideoProvider
+ new(provider: VideoProvider)
-- the provider closes a room once its host leaves, so a
-- room is opened for one visit, never kept for the day
+ roomFor(visit: VisitId): RoomLink
return RoomLink.at(provider.openRoom(visit.text()))
After, both notes are gone. The first is deleted (rule 4), and the
second, once corrected, would only repeat the signature, so it is
deleted too (rules 3 and 4). The comment that stays sits above the
method, where the Before's comments sat, and gives the reason a room
serves one visit: the provider closes a room once its host leaves. That
is the provider's behaviour, which no name in the clinic's code can
carry (rule 2). It is a note for the adapter's maintainers, not a
contract under the signature, which honouring substitutability, rule 4,
places there for callers.
VideoProvider is taken to be the provider's client, whose openRoom
takes the visit's identifier as text and answers the room's address as
text. visit.text() answers the identifier as text, RoomLink.at is
taken to be the named factory of the clinic's RoomLink value, and
VisitId is the visit's identity, as the antipatterns skill uses it.
openRoom is taken to raise nothing, and the provider's failures are
left out of the fences.
The fences store nothing. Each version opens one room per roomFor: the
constructor sets provider before roomFor reads it, and each roomFor
sends one openRoom.
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 comment above each line that says what the line does.
- A comment whose number, name or order differs from the code beside it.
- Code commented out and left in place.
- A comment that lists who changed the code and when.
- A long comment that explains what a badly named method does.
Common mistakes
- Writing a comment to explain a name instead of changing the name.
- Fixing the code and leaving the old comment beside it.
- Deleting a comment that held an outside constraint along with the
noise.
- Keeping a decision's history in a block of comments.
- Commenting a surprising behaviour that a test could show.
Related skills
Further reading
1---2name: oo-commenting-what-code-cannot3description: Use when comments or notes repeat the code or contradict it, or when a note must explain a reason or a warning no well-chosen name can explain.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-commenting-what-code-cannot7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Commenting What Code Cannot Say1213**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## Overview1920Code carries most of what a reader needs: a name says what a class or21method is for, a value type holds a rule, and a test names a behaviour.22This skill keeps the small remainder honest. It puts a reason, an outside23constraint, a trade-off or a warning in a comment only where no name,24type or test can carry it, deletes the comments that repeat what the code25already says, and treats a comment that disagrees with the code as a26defect in the change that finds it. Every comment it keeps describes the27code as it is now.2829## When to use3031- A comment restates the name or the signature beside it.32- A comment disagrees with the code, and a reader cannot tell which one33 is right.34- A comment block lists who changed the code and when, or what it35 replaced.36- Code no longer used sits commented out in the file.37- A reader asks why a line takes the longer road, or what limit another38 system or organisation sets.39- A comment is about to explain a name that could say the same thing.40- A surprising behaviour needs either a comment or a test.4142## When not to use4344- The question is why a choice that reaches across modules was made, and45 where its record lives: that is46 [documenting design decisions](../oo-documenting-design-decisions/SKILL.md).47- The question is what a class or method should be called: that is48 [naming classes and methods](../oo-naming-classes-and-methods/SKILL.md).49- The question is what a type's contract must promise so that every50 subtype keeps it: that is51 [honouring substitutability](../oo-honouring-substitutability/SKILL.md).52- The text is for people who do not read the code, such as a guide for53 receptionists or the reference of a published interface: outside this54 skill.5556## Core rules57581. Rule. **Say it in the code first, and comment only what is left: a59 name that says what a class or method is for, as naming classes and60 methods, rules 1 to 3, asks; a value type for a primitive that carries61 a rule, as modeling values and entities, rule 5, asks; a method named62 for a step that needed a comment; or a test named for a behaviour.**63 Each of those carries its meaning where a reader meets it, so no64 second text has to be kept true. A comment comes after them, and only65 for what none of them can hold.66672. Rule. **Comment why, not what: a reason the code cannot show, a68 constraint from outside the code, such as what another system accepts,69 a trade-off the team chose, or a warning about a consequence a reader70 would not expect.** A comment that describes the next line competes71 with it: a reader follows the note and skips the line, and the note72 goes stale when the line changes. Keep the note beside the code it73 explains, short enough to read in one pass.74753. Rule. **Treat a comment that disagrees with the code as a defect, and76 fix it in the change that finds it: find out which one is right, from77 the people who own the rule or from a test, then correct the comment78 or the code, and add a test when the code was wrong.** Leave neither79 the wrong note nor the wrong line for a later change. A note corrected80 to match a defect teaches every reader the defect.81824. Default. **Delete a comment that repeats what the code already says,83 such as a comment naming the constructor above it.** A second copy of84 one fact is one more copy to keep true, and it is the copy that drifts85 first.86 The exception is the contract under a public method's signature,87 where honouring substitutability, rule 4, asks for one: callers read88 the contract instead of the body, so it stays even where the body89 happens to show the same thing.90915. Rule. **Keep history out of comments: who changed a line, when, and92 what it replaced belong to version control; a choice's reasons and the93 options weighed belong to its decision record, as documenting design94 decisions, rule 2, keeps them; and code no longer used is deleted, not95 commented out.** Read the note as a statement about the code in front96 of you, with one line at most naming the record that gives the reasons.97986. Judgement. **Choose between a comment and a test for a behaviour that99 would surprise a reader.** A test named for the behaviour fails when100 the behaviour changes, where a comment stays quiet through the same101 change. A comment can still carry a reason no test can show, such as a102 limit another organisation sets. What tips the balance is whether a103 test can show the behaviour: when it can, write the test, and keep at104 most a one-line reason beside the code.105106## Pattern107108`HostedVideoRooms` is the adapter behind the clinic's `VideoRooms` port109for telehealth visits, and the one class that knows the provider's110client (crossing system boundaries, rule 3), so the outside constraint111is written here and on no domain class.112113Before:114115```text116class HostedVideoRooms implements VideoRooms117 - provider: VideoProvider118 -- the constructor119 + new(provider: VideoProvider)120 -- opens one room per patient for the whole day121 + roomFor(visit: VisitId): RoomLink122 return RoomLink.at(provider.openRoom(visit.text()))123```124125In the Before, "the constructor" repeats the code beside it (rule 4),126and "one room per patient for the whole day" disagrees with it: `roomFor`127opens a room for a visit, so the code is right (rule 3).128129After:130131```text132class HostedVideoRooms implements VideoRooms133 - provider: VideoProvider134 + new(provider: VideoProvider)135 -- the provider closes a room once its host leaves, so a136 -- room is opened for one visit, never kept for the day137 + roomFor(visit: VisitId): RoomLink138 return RoomLink.at(provider.openRoom(visit.text()))139```140141After, both notes are gone. The first is deleted (rule 4), and the142second, once corrected, would only repeat the signature, so it is143deleted too (rules 3 and 4). The comment that stays sits above the144method, where the Before's comments sat, and gives the reason a room145serves one visit: the provider closes a room once its host leaves. That146is the provider's behaviour, which no name in the clinic's code can147carry (rule 2). It is a note for the adapter's maintainers, not a148contract under the signature, which honouring substitutability, rule 4,149places there for callers.150151`VideoProvider` is taken to be the provider's client, whose `openRoom`152takes the visit's identifier as text and answers the room's address as153text. `visit.text()` answers the identifier as text, `RoomLink.at` is154taken to be the named factory of the clinic's `RoomLink` value, and155`VisitId` is the visit's identity, as the antipatterns skill uses it.156`openRoom` is taken to raise nothing, and the provider's failures are157left out of the fences.158159The fences store nothing. Each version opens one room per `roomFor`: the160constructor sets `provider` before `roomFor` reads it, and each `roomFor`161sends one `openRoom`.162163## Red flags164165Places to look, not verdicts. A red flag becomes a finding only with166evidence: a measurement, a reproducible bug, or a failing test.167168- A comment above each line that says what the line does.169- A comment whose number, name or order differs from the code beside it.170- Code commented out and left in place.171- A comment that lists who changed the code and when.172- A long comment that explains what a badly named method does.173174## Common mistakes175176- Writing a comment to explain a name instead of changing the name.177- Fixing the code and leaving the old comment beside it.178- Deleting a comment that held an outside constraint along with the179 noise.180- Keeping a decision's history in a block of comments.181- Commenting a surprising behaviour that a test could show.182183## Related skills184185- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule186 labels.187- [oo-documenting-design-decisions](../oo-documenting-design-decisions/SKILL.md)188 rule 2 keeps a choice's reasons and the options weighed in a record.189- [oo-naming-classes-and-methods](../oo-naming-classes-and-methods/SKILL.md)190 rules 1 to 3 choose the name that makes a comment unnecessary.191- [oo-modeling-values-and-entities](../oo-modeling-values-and-entities/SKILL.md)192 rule 5 replaces a primitive that carries a rule with a value type.193- [oo-honouring-substitutability](../oo-honouring-substitutability/SKILL.md)194 rule 4 places a contract where callers read it.195- [oo-testing-object-oriented-code](../oo-testing-object-oriented-code/SKILL.md)196 names a test for the behaviour it shows.197198## Further reading199200- [Comments worth keeping](references/comments-worth-keeping.md)