Code cannot lie about what it does.
It runs,
and running is a confession.
A comment can lie for years
and nothing will stop it.
Nobody compiles the prose.
Somebody once wrote
"temporary, remove after the migration"
above a function
that is now load bearing.
The migration finished
in a year nobody remembers.
The sentence stayed.
Every reader since
has spent ten minutes
deciding whether to believe it.
That is the real cost.
A wrong comment does not merely fail to help.
It taxes everyone who arrives after,
because now they have to check,
and checking means reading the code
they were trying to avoid reading.
They read the sentence.
They read the function.
They find the gap.
Then they have to decide
which one is the mistake.
Silence would have been cheaper.
So write fewer of them, and better ones.
Do not narrate.
Nobody needs a line
explaining that the loop loops.
Write down the thing
the code physically cannot say.
Why the retry count is three.
Which vendor bug this works around,
with the ticket number,
so the next person can find out
whether it has been fixed.
Why the obvious approach
was tried and abandoned.
That is knowledge.
The rest is decoration.
Then treat it like code.
When the behaviour changes,
the sentence changes in the same commit,
or the sentence goes.
Deleting is allowed.
A comment you no longer trust
is not an asset you are preserving.
It is a rumour you are hosting.
And where you can,
turn the comment into something
that breaks when it becomes wrong.
A name.
A test.
An assertion with a message in it.
Those cannot drift,
because the build shouts.
The words above the function
have no such alarm.
They will sit there,
confident and stale,
long after the reason evaporated,
telling somebody in their second week
something that was true once
and is now just furniture.
– Serguey Asael Shinder
Top comments (0)