Somewhere in your code
there is a strange condition
with a comment above it.
See the ticket.
And a ticket number.
You go to look it up.
The ticket system was replaced
three years ago.
The migration brought over
the open tickets
and left the closed ones behind.
The wiki page it also mentions
lived on a server
that was switched off.
The chat thread
where the decision was made
was in a tool the company
stopped paying for.
The condition is still there.
It still runs every day.
Nobody alive in the team
knows what it is protecting.
Here is the thing to plan for.
Code lasts longer
than the tools around it.
The tracker,
the wiki,
the chat,
the design tool,
the place you keep diagrams,
get replaced every few years,
by a new vendor,
a merger,
a cost review,
or somebody who likes a different product.
The repository
tends to survive all of them.
It gets moved,
but it gets moved whole,
history and all,
because code is the one thing
nobody dares to leave behind.
So every link from the code
to somewhere else
is a promise
that the somewhere else
will still exist.
Most of those promises
will be broken,
and not by anybody's mistake.
A link is fine.
A link on its own
is a bet.
When the reason matters,
write the reason
where the code is.
Two or three plain sentences
in the comment,
the commit,
or a decisions file in the repository.
What happened.
What this protects against.
What would have to be true
for it to be safe to delete.
Then add the link
for anyone who wants the long version,
while it lasts.
The same goes for diagrams.
Keep a text version
next to the code
that any future tool can read.
And when your company
does replace a tool,
before the old one goes dark,
search the code
for every address that points into it,
and pull in whatever
those pages were holding up.
The next migration
is already on somebody's list.
Make sure your reasons
do not depend on it going well.
– Serguey Asael Shinder
Top comments (0)