Ask HN: How do you maintain personal annotations for code you don't control?

I spend significant time reading and understanding codebases that I don't control (open source libraries, internal legacy systems, etc.). As I build understanding, I need to document my insights, gotchas, and mental models - but these notes are purely personal and shouldn't be part of the actual codebase.

My challenges:

1. These annotations need to be tightly coupled with specific locations in the source code (particular functions, variables, or even specific lines)

2. The underlying code changes regularly (new versions, updates from maintainers) which can break the connection between my notes and the code

3. My notes are private - they include half-formed thoughts, questions, and sometimes critical observations that wouldn't be appropriate as public comments

4. I want to preserve this knowledge across different machines and working environments

I've tried various approaches: - Local IDE bookmarks (lost between sessions) - Separate markdown files (hard to maintain precise code references) - Private forks with comments (becomes unmaintainable as source evolves)

I'm curious how others solve this problem. Do you have a systematic approach for maintaining personal annotations on code that's not under your control? How do you handle the challenge of the code evolving while keeping your notes relevant?

Would especially love to hear from people working with large codebases or those who regularly need to dive deep into external dependencies.

Leo editor allows to keep in sync its outline which combines your annotations and external files.

Obviously it isn't bulletproof and needs maintenance when it can't merge external changes automatically.

https://leo-editor.github.io/leo-editor/

This is the first time I've ever heard of someone keeping private source-line-attached notes in a codebase. I work with very large codebases, but if I discover things about the codebase that required spelunking, I generally turn them into comments or documentation.

Of the requirements that you've laid out, I'd suggest that you need to either relax requirement 2 or 3:

If you relax requirement 2, you could keep your notes in a private fork.

If you relax requirement 3, and make your notes suitable for public consumption, you could submit your notes as comments and make the codebase easier for everyone to understand. (Or, at least, you could submit some of your comments, making the remainder easier to maintain privately.)

GitHub issue comments. You can link to code in GitHub that's anchored to a specific commit. If it's in the same repo GitHub will inline the code into the issue git you. For separate repos I sometimes link and then manually copy in the code block myself.

I recently came across a VS Code extension that does pretty much what you're looking for -

> Out-of-Code Insights is a Visual Studio Code extension that allows you to add annotations, notes, and comments without modifying your source files.

https://marketplace.visualstudio.com/items?itemName=JacquesG...

GitHub:

https://github.com/JacquesGariepy/out-of-code-insights/