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

The lack of syncing doesn't bother me, because the purpose of taking notes always falls into one of these categories:

1. I read the code to get an idea of how something works. The code is there to make examples/variable names concrete, but I don't need to know the exact implementation.

If the notes need to sit in the code, usually that's because the answer spans multiple methods (eg "what does an e2e request look like?"). A set of comments on outdated code is always good enough for me.

Otherwise, a lot of times the answer can be summarized in one line (eg "where is the state tracked?" -> in FooBarClass). These can go into personal notes.

2. I need to know the implementation and it is complex and hard to follow.

If I need to know the implementation, either it is because I'm actively working on it, or I need to make [complex idea] more concrete in my head.

If it's the former, usually I'll have memorized it by the time I read through it.

If it's the latter, by the end of it I'll have gotten the main idea and it's fine to forget the implantation details.

Building an open source code review system using git notes would be great though.

I have my source code in one directory, and in another I use Sphinx to make the documentation. In the documentation, I reference certain sections of code, which you can do by line number, or you can do by some pattern to begin and end.

Since I control all my source code, I put in comments with certain flags for regions of code.

I can then reference said section of code as follows

  .. literalinclude:: ../../src/demo06/demo.py
     :language: python
     :start-after: doc-region-begin define uniform scale
     :end-before: doc-region-end define uniform scale
     :linenos:
     :lineno-match:
     :caption: src/demo06/demo.py

The generated book is here https://billsix.github.io/modelviewprojection/

For your purposes, using a third party's code, I would make a new git repository, and copy the current status of their code in, I would then annotate the sections that I want to with comments, And then generate the documentation using Sphinx, referencing you annotations of their code

There are tools for aspects of all these areas, but still feel unsolved (easy, feature-full).