I wanted a code bookmark plugin. Not a full-featured one. Just a really simple one. For some reason, I couldn’t find anything that quite fit.

I looked for something that would let me bookmark arbitrary pieces of code and then jump back to them later, but everything I found seemed to have a slightly different idea of what a bookmark should be.

The closest thing I found was Harpoon. I do use Harpoon, but for a different purpose.

My use case is usually when I’m trying to understand a particular code path in a large codebase. I might start from a function, find its references, follow a few calls, jump somewhere else, and gradually build a picture of how things connect.

I want to keep some of those locations around, but I don’t necessarily want the whole call hierarchy.

I also want to write random notes around the bookmarks.

Simply speaking, I wanted something closer to Markdown links:

Some note about this part of the code.

<interesting_function>
<another_thing>

This explains why these two things are related.

<somewhere_completely_different>

Except the links should point directly to code.

So I wrote scattermarks.nvim, a super tiny bookmark plugin.

It has only two commands.

LoclistToScratch takes the definitions or references in a location list and turns them into my bookmark syntax in a new buffer.

BookmarkGo lets me put my cursor on a bookmark and jump directly to the referenced code.

Now I can have a note like this:

The request enters here:
OrderController.cs|24|var order = await orderService.Create(request);|~\projects\Demo\Orders\OrderController.cs

The service does the validation first:
OrderService.cs|41|validator.ValidateAndThrow(request);|~\projects\Demo\Orders\OrderService.cs

Then creates the domain object:
OrderService.cs|48|var order = Order.Create(request.CustomerId, request.Items);|~\projects\Demo\Orders\OrderService.cs

TODO: Need to see what happens inside Order.Create:
Order.cs|36|public static Order Create(Guid customerId, IReadOnlyList<OrderItem> items)|~\projects\Demo\Orders\Order.cs

There is no tool that perfectly fits everyone’s workflow. Sometimes the easiest way to get the tool you want is to make the tiny thing yourself.

Being able to shape your tools around the way you actually work can be useful.