News for hackers. Stuff that matters.
Re:How to annotate everything by Splognosticus on Wednesday November 27, 2019 @02:39PM (#21651224)
Why not just actually use comments? If it's worth explaining to new developers it'll likely be useful later when you've simply forgotten why something is the way it is.
Re:How to annotate everything by cfors on Wednesday November 27, 2019 @03:12PM (#21651599)
Seriously. Especially when something seems like a bizarre choice in the code, I'll provide a link if there is a corresponding GitHub issue or code regarding it.

I've never had an issue with GitHub issues regarding linkrot, but it happens quite frequently when linking actual source code, especially code not in your control. Not sure what a better solution is for that, unfortunately.

I generally justify it by the anecdotal observation that the code is generally not being used anymore by the time the link dies out, but that is far from an ideal justification.

Re:How to annotate everything by jakub_g on Wednesday November 27, 2019 @03:46PM (#21651932)
Assuming you use GitHub for source control:

- Go to GitHub.com repo and find the file (You can use 't' keyboard shortcut to find it)

- Press 'y' on keyboard to replace 'master' with its SHA1 in the URL

- Click on the interesting line of code

- You have a forever-valid link (assuming no push --force) to the exact line of code

Re:How to annotate everything by gugagore on Wednesday November 27, 2019 @04:54PM (#21652538)
I thought a push --force would change the hash, anyway.
Re:How to annotate everything by jakub_g on Wednesday November 27, 2019 @05:00PM (#21652601)
I meant that push --force may make the given commit disappear if it's not referenced by any branch and the repo gets garbage collected on the backend, then the URL will 404.
Re:How to annotate everything by TeMPOraL on Wednesday November 27, 2019 @03:57PM (#21652066)
Because such annotations are for you to help you comprehend, not something you want to actually leave in the codebase.
Re:How to annotate everything by retsibsi on Thursday November 28, 2019 @02:43AM (#21655364)
Not trying to be a smartarse, but isn't that what comments are for? If they aid your comprehension, there's a reasonable chance they'll also help someone else in the future.
Re:How to annotate everything by TeMPOraL on Thursday November 28, 2019 @02:55AM (#21655410)
There's overlap, but annotations are more throwaway and task-oriented. Once done with your code study, you wouldn't want to commit to the main repo all the little yellow highlights, the "!!!" notes, the hand-drawn arrows connecting code lines, the "does X, but ask Fred" remarks, etc.

Also, separating these out would let one to design tooling that's more suitable for reading and annotating than editing. When studying code, I'd prefer to do it on a tablet, with an experience closer to a PDF reader than IDE.

Re:How to annotate everything by retsibsi on Friday November 29, 2019 @11:12PM (#21668463)
That makes sense, thanks.