Convention

Sometimes it is useful to document connections between related pieces of code.

Any text of the form anchor: <ID> is considered a link to all other occurrences of <ID>. The IDs are exactly 8 alphanumeric characters, case sensitive. (That particular format was chosen because I happened to use the DuckDuckGo password generator to create the IDs before I made the extension.)

This is better than using file paths and line numbers, because when the code moves around, the links don't break. As an added benefit, the links are symmetric, so you get back-links for free. And there can be more than two pieces connected by a single ID.

There is a VSCode extension that helps with using this convention.

Applications

Duplication is cheaper than the wrong abstraction. But it still has costs:

• risk of divergence
• untracked technical debt

Having a low-friction way to document connections mitigates both.

Guilt-free copy-pasting

Implement the feature now, add a // TODO: dedup (anchor: 2HRHM2ag) comment, and tell yourself you'll refactor it later.

Up-to-date documentation

Use anchors to link code to related docs. When somebody changes the code in the future, they'll see that the doc exists elsewhere and maybe even go out of their way to update it.

Synchronizing alien stacks

For example, the list of application routes can be present both in a switch statement in router.js and in Caddy config. There is no easy way to factor it out without resorting to code generation. My recommendation usually is to maintain the correspondence by hand, and rely on anchors as a reminder.

VSCode extension features

Navigation. CodeLens shows other occurrences; click to jump. Searches the whole workspace and respects .gitignore.

ID generation. Code completion after anchor: suggests a new random ID.

Agent instructions

Copy this to your AGENTS.md file:

# Anchors

If you see an `anchor: <ID>` comment, search the codebase for that ID to find connected code.
Changes in one place may require updates to the others.
For the curious, see https://github.com/Vlad-Shcherbina/anchor