A link in a comment can explain a piece of code today and become useless when the ticket system, wiki, or chat service behind it disappears. For behavior future maintainers may need to understand, keep the reason in the repository itself; treat external links as supporting detail, not the only explanation.
Why a code link can lose its value
In his September 30, 2025 DEV Community essay, “Every Link in Your Code Points at a Tool You Will Replace,” Serguey Asael Shinder describes a familiar maintenance risk: code outlives the systems around it. A comment might send a maintainer to a ticket system that was replaced, but closed tickets did not survive the migration. A wiki may be switched off; a decision thread may sit in a chat service the company no longer pays for.
These are the essay’s illustrative scenarios, not evidence of how often companies replace tools or lose records. The practical point is narrower: a reference outside the repository cannot guarantee that its explanation will remain available for as long as the code does. As Shinder puts it, “A link on its own is a bet.”
What to preserve beside consequential code
When a condition, workaround, or unusual implementation protects against a specific failure, leave a short explanation where maintainers can find it without relying on another service. Two or three plain sentences can cover the essentials:
#1 Best Overall
- What happened: describe the relevant incident or behavior, without assuming the reader can open an old ticket.
- What the code protects against: connect the condition or workaround to the failure it prevents.
- What would make removal safe: state the condition, verification, or system change that would justify deleting it.
For example: “Keep the retry guard because the upstream service sometimes returns a partial response during recovery. Removing it is safe only after the service guarantees complete responses and the recovery path is verified.” This is an illustrative pattern, not a claim about a particular service or incident.
Choose the repository location that fits the information. A code comment works when the rationale is tightly tied to a nearby condition. A commit message can preserve why a change was made in its history. A decision file is more suitable when the reasoning affects multiple files or needs a durable, discoverable record. These are practical options, not formats ranked by comparative testing.
Keep external references useful, but nonessential
Linking to a ticket, discussion, or specification can still help while the source remains available. Pair the link with enough local context that a maintainer can understand the code if the destination fails. Do not make “see ticket” the whole explanation for behavior whose purpose may not be obvious from the code.
The local note need not reproduce every conversation or attachment. Preserve the decision and its technical rationale—the parts a future maintainer needs to evaluate whether the code is still necessary. The external record can remain additional detail.
Recommended Free Tools
Make diagrams readable without their original editor
A diagram can communicate relationships that are awkward to explain in a comment, but an image or editor-specific file may be hard to use after its tool is gone. Keep a text version near the relevant code that describes the important elements and connections. That gives maintainers a readable account even if they cannot open or edit the original diagram.
The text companion should preserve meaning rather than attempt to duplicate every visual detail. Identify the components, the direction of important flows, and any decision points that affect the code. Keep it close enough to the implementation that a reader can locate both.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Before retiring a company tool
Shinder’s advice also applies during a migration, while the old system is still accessible. Search source code for references into the service being retired, then identify which linked records explain behavior that will remain in use.
- Search the repository for the old service’s URL patterns, domain, or recognizable link prefixes.
- Review the references in context and identify any that contain rationale, decisions, or diagrams needed to maintain active code.
- Preserve the relevant explanation in comments, commit history, repository decision files, or text-based diagram notes, as appropriate.
- Verify that the local record explains the behavior without requiring access to the old tool.
This is a preservation step, not a reason to copy every old ticket into the repository. Focus on information that explains code that remains important, and retain only the context needed to understand or safely change it.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteBest Value
A practical test for a code comment
Read the comment as if the linked service and its records were unavailable. If it tells you what the code does but not why it exists, or if it gives no clue what would make the code safe to remove, add that missing rationale locally. Shinder’s warning is a maintenance principle rather than a quantified prediction: “Code lasts longer than the tools around it.”
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
