21–30 of 45 posts
Consider using special "symbols" in comments like "MYDOCS_XXX" that you search for in your modified version of the code base, and refer to in other places. These will survive renames of function names etc by the upstream authors.
That shouldn’t be difficult. Most code repository systems support links to exact line numbers in specific commits, for example like [0]. Even in the event that the links stop working, you can still identify the commit hash, file name and line number from the URL.
[0] https://github.com/curl/curl/blob/3b057d4b7a7e6b811245fd0312...
handy, if you’re in the emacs ecosystem.
2. The underlying code changes regularly (new versions, updates from maintainers) which can break the connection between my notes and the code
Maybe depend on more loosely coupled notes?
You say they "need", but realistically they don't really need "to be tightly coupled with specific locations in the source code", that's just a nice to have.
Re: critical tone, instead of saying “this is a useless garbage fire” maybe something like “it is not yet apparent how this interacts with blah blah.” There’s always a way to phrase it where it’ll plant the seeds of how you want the reader to feel about it without being overt.
My 2c, anyway.
[flagged]
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/
To expand: With Leo editor, you convert the document/file into a tree of nodes (one way to do this is to make each function a node - they have plugins to do it automatically for well known languages like C++). Let's say you make a particular function a node. You can then make a new document in your own filesystem which has your notes, but you can make a "live" copy of the node linking to that function.
You now can see your notes along side that function. If you modify the "live" node, it will actually modify the original source file. Similarly, if the code changes (e.g. with a git pull), then Leo tends to do a good job of updating the references so that your node still points to the correct function.
The editor is a bit weird to learn, but once you get the hang of it, it's extremely powerful. I used this technique often while debugging messy bugs. I'd have my own document with live nodes to the test case, the test collateral, relevant source code, etc. Each node was simply a view to a portion of some corresponding file. This way, even though everything related to the test was scattered across several files, I could see everything related to the bug (test + source code) all in one document.
It's the one powerful feature that has yet to be replicated in Emacs.
If you're working within git, maybe `git notes` fit your use case? You can basically attach notes to various Git objects, without changing the objects themselves. https://git-scm.com/docs/git-notes
[flagged]
This sounds like human-generated nonsense
i.e. your input can become less than helpful, and becomes a liability or outright errata.
Have a nice day, =3