I opened an old TypeScript service after a few weeks away from it and found this:
// TODO: fix retry logic
async chargeCustomer(input: ChargeInput) {
// ...
}
The comment was technically useful when I wrote it.
Later, it was almost useless.
It did not tell me why the retry logic was risky. It did not tell me whether the issue was still open. It did not tell me if the problem was duplicate charges, provider timeouts, idempotency keys, or cleanup I never finished.
That is the problem I kept running into with TODO and FIXME comments.
They are easy to write, but they lose context fast.
So I built GhostMap, a VS Code extension for structured
The problem with normal TODO comments
A normal TODO usually captures one thing:
Something is unfinished.
// TODO: handle timeout
That is fine for short-lived notes.
It breaks down when the comment stays in the code longer than expected.
After a week or two, you usually need more than the note itself:
- What is the actual risk?
- Is this still open?
- Who should care about it?
- Does it belong to the function below it, the whole class, or a larger section?
- Is it a cleanup task, production risk, migration marker, or review note?
- Is it still relevant after the last refactor?
The comment is close to the code, which is good.
The problem is that it has no structure.
Issue trackers solve some of this, but they are not always the right place for code-local context. Pull requests solve some of it too, but PR context is often gone from your head by the time you revisit the file.
I wanted something lighter than a tracker and more durable than a random TODO.
The smallest useful upgrade: structured comments
Instead of this:
// TODO: retry issue
GhostMap uses this:
// @ghost #payment-retry status:in-progress description: retry can double-charge if provider timeout returns late
That one line carries more useful information:
anchors.
You can click a tree item to jump to the matching line.
You can also use syntax in V1
- Some language-specific symbol edge cases are still being cleaned up
- Support quality varies by language and file type
- GhostMap is source-available under a non-commercial license, not OSI open source
- Personal, educational, evaluation, testing, and other non-commercial use are allowed
- Company, business, production, revenue-generating, client, resale, white-label, marketplace-republish, and competing-product use require written authorization
I am being upfront about this because developer tools only earn trust when the rough edges are visible.
I would rather say what is missing now than pretend the MVP is more mature than it is.
Why I built it this way
I did not want another SaaS dashboard.
I did not want another place where code context goes to die.
The code already has the most important location context.
The missing part is structure.
A plain comment says:
remember this
A structured annotation says:
remember this, here is what it is called, here is its state, here is why it matters, and here is where it lives
That small difference makes old code easier to re-enter.
It also makes TODO-style comments feel less disposable.
Try it
GhostMap is available on the VS Code Marketplace:
Product site:
https://ghostmap-liard.vercel.app/
If you already use TODO Tree, Better Comments, VS Code Outline, or your own TODO convention, I would especially like feedback on one question:
Would structured annotations fit your workflow, or should this stay closer to normal TODO comments?
SOCIAL SHARE CARD GENERATOR