7 ms·

How to annotate code? I've once in a while wanted some tool to annotate code as I explain it to new developers, or as I explore code I'm unfamiliar with, withou

How to annotate code? I've once in a while wanted some tool to annotate code as I explain it to new developers, or as I explore code I'm unfamiliar with, without having to write comments directly in the source code. The closest I've found to do this is bookmarks in IntelliJ using the name of the bookmark as the annotation.

Splognosticus 7y ago
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.
- cfors 7y ago
  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.
  - jakub_g 7y ago
    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
    - gugagore 7y ago
      I thought a push --force would change the hash, anyway.
      - jakub_g 7y ago
        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.
- TeMPOraL 7y ago
  Because such annotations are for you to help you comprehend, not something you want to actually leave in the codebase.
  - retsibsi 7y ago
    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.
    - TeMPOraL 7y ago
      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.
      - retsibsi 7y ago
        That makes sense, thanks.
TeMPOraL 7y ago
I second it. And not for just teaching someone - but for understanding unfamiliar codebases. I'd like a IDE/editor-like tool that would open code read-only, but allow me to annotate it - attach notes and crosslinks to other locations in code, highlight and cross out code fragments, draw on top of it, etc. All of that on top of navigation utilities you'd expect from a code editor - text search, jump to definition, etc. A tool designed for reading, not for writing. The closest thing I know to that experience, which I occasionally use, is printing code from editor/IDE into PDF, and using a quality PDF viewer. While useful for a couple of files I want to focus on, this doesn't help explore the codebase.
pmoriarty 7y ago
Sounds like a job for Literate Programming.[1] This could also be done, for instance, in org-mode, with embedded source-code blocks. Normally, the source in the org's source code blocks live directly in the org document itself, but there's no reason it couldn't pull in the source from external documents instead. I wouldn't be surprised if there's isn't already an extension or org feature that does this. [1] - https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
amelius 7y ago
Some editors allow you to create regions of text which you can collapse/expand. You can do this in Vim, for example. So you could use these regions for comments which are not visible when you're coding.
karlicoss 7y ago
Hey, author here! You want to search for "literate programming". I'm a big fan of it, and working on a post overviewing available options for it. Stay tuned :)

Splognosticus 7y ago

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.

cfors 7y ago
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.
- jakub_g 7y ago
  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
  - gugagore 7y ago
    I thought a push --force would change the hash, anyway.
    - jakub_g 7y ago
      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.
TeMPOraL 7y ago
Because such annotations are for you to help you comprehend, not something you want to actually leave in the codebase.
- retsibsi 7y ago
  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.
  - TeMPOraL 7y ago
    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.
    - retsibsi 7y ago
      That makes sense, thanks.

TeMPOraL 7y ago

I second it. And not for just teaching someone - but for understanding unfamiliar codebases. I'd like a IDE/editor-like tool that would open code read-only, but allow me to annotate it - attach notes and crosslinks to other locations in code, highlight and cross out code fragments, draw on top of it, etc. All of that on top of navigation utilities you'd expect from a code editor - text search, jump to definition, etc. A tool designed for reading, not for writing. The closest thing I know to that experience, which I occasionally use, is printing code from editor/IDE into PDF, and using a quality PDF viewer. While useful for a couple of files I want to focus on, this doesn't help explore the codebase.

pmoriarty 7y ago

Sounds like a job for Literate Programming.[1] This could also be done, for instance, in org-mode, with embedded source-code blocks. Normally, the source in the org's source code blocks live directly in the org document itself, but there's no reason it couldn't pull in the source from external documents instead. I wouldn't be surprised if there's isn't already an extension or org feature that does this. [1] - https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming

amelius 7y ago

Some editors allow you to create regions of text which you can collapse/expand. You can do this in Vim, for example. So you could use these regions for comments which are not visible when you're coding.

karlicoss 7y ago

Hey, author here! You want to search for "literate programming". I'm a big fan of it, and working on a post overviewing available options for it. Stay tuned :)