I don't anymore and when I did the code didn't change much. But I haven't seen anyone mentioning processing the AST. Some things would break between changes, but if the language the code uses has a good AST traversal library, you could assign your notes to parts of the tree rather than source code locations, falling back to source code locations when that fails. It would still need manual maintenance, but would at least be less fragile than using solely line locations.
Ask HN: How do you maintain personal annotations for code you don't control?
11–20 of 45 posts
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#12[dead]
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#13If 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.
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#14[flagged]
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#15I used codestream with two of my previous teams and absolutely loved it. I don’t remember if you can keep annotations private but I see plenty of value in allowing the rest of the team to see what questions/note you have. In any case, I believe they open sourced the whole thing so you could see how they handled code changes
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#16I don't anymore and when I did the code didn't change much. But I haven't seen anyone mentioning processing the AST. Some things would break between changes, but if the language the code uses has a good AST traversal library, you could assign your notes to parts of the tree rather than source code locations, falling back to source code locations when that fails. It would still need manual maintenance, but would at le…
BABLR should eventually offer strong support this use case!
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#17If 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
Is this what GitHub reviews use?
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#18Re: Ask HN: How do you maintain personal annotations for code you don't control?
#19I maintain a branch with my comments inline.
If the underlying code changes, I just update my comments.
Re: Ask HN: How do you maintain personal annotations for code you don't control?
#20I do my absolute best to write code that does not require many or an comments or annotations because of the pain points described. I assume you're not referring to things like documenting "infrastructure" or "overall design" or "how to get started" as they don't change much and I just put those in a readme in the repo. For the nuts and bolts itself, this involves
Carefully naming variables and classes in obvious and consistent ways. I will spend time refactoring code so that it is named consistently and behaves as named.
Very small functions and classes (but not smaller than they need to be). This lets me use more named functions which gives me more description. It also typically gives me a nice hierarchy of how things occur, so whatever main "driver" function I have is pretty declarative and light on logic. It avoids big "god" functions or classes which tend to get cluttered and are often the hardest to break down or read.
Enforce obvious and established patterns. These again go in names, but if I'm using CQRS, then I'll have lots of CQRS, handler, registrar, etc in the names. If I have a factory it has Factory in the name. When you see these you know what and how things are organized.
Related to the above, no "clever" code and no inconsistent code. I'll write more "inefficient" code if it's not a bottleneck rather than something tight which was a premature optimization. If it's not normal for the established patterns, but could be forged into something consistent, I do the latter.
Lots and lots of tests. Tests describe behavior which tends to be pretty immutable OR if I have a requirement on behavior change, the test will fail at some point and needs to be reconsidered so gets my renaming attention. That last part is very important. Most testing frameworks let add plain language names/failure conditions, so if the behavior has changed the test starts going red and it doesn't let you forget about it. Those often become my documentation/annotations.
I will use comments when I've written something that needs to be structured outside of the above. These tend to be rare and typically pretty dense "black box" places, like when I've implemented a numerical or other very specific algorithm. As such they don't tend to get touched very often and I will write unit tests to make sure behavior is enforced.