5 ms·

I want a tool that lets me annotate a codebase but with the notes stored locally and not in the code. This would mostly be for corporate code bases so I can tak

I want a tool that lets me annotate a codebase but with the notes stored locally and not in the code. This would mostly be for corporate code bases so I can take notes/ leave more explicit warnings for others. Less "Turns markdown into react components" and more "If you have to touch this, you need to go to file x, add it there" I understand this is imperfect but so is the codebase I work on.

vmsp 4y ago
There's an Emacs mode that does this called annotate. But why would this be better than just leaving a comment on the file? https://github.com/bastibe/annotate.el https://github.com/bastibe/annotate.el
- exdsq 4y ago
  Maybe if you’re working on partially open source code you want a layer of comments separate to the code that aren’t version controlled so you can mention internal bits to each other?
- Frotag 4y ago
  Personally I don't want to have to open the browser to get more detailed docs. I'd rather have it next to the code it's referencing. (Especially if it's just a side project where sphinx or whatever is overkill.)
_boffin_ 4y ago
This isn't explicitly what you're asking for, but it's something: https://plugins.jetbrains.com/plugin/16998-notebook https://plugins.jetbrains.com/plugin/16998-notebook I'm currently thinking of how to do exactly what you described with intellij plugin's. I've realized, that for me, i'm best when i print out code, use rulers to draw dividers between methods and other stuff, and then take notes for different parts of the code. don't mind the horrid writing that's most likely unintelligible: https://i.ibb.co/ByTm7vt/notes.jpg https://i.ibb.co/ByTm7vt/notes.jpg
Frotag 4y ago
I've always wanted something similar to git blame for this. Where I can add notes to sets of lines and toggle whether I want the IDE to display them. Sort of like writing on those overhead projector sheets and saving it to a nearby .notes file or whatever. It'd probably be hell to maintain but a dev can dream. Tangential, but it sucks that it's hard to even find discussion on something like this. Closest I've found is the fictional "an editor" talk here https://www.destroyallsoftware.com/talks/a-whole-new-world https://www.destroyallsoftware.com/talks/a-whole-new-world
aitchnyu 4y ago
Aren't there tools that suggest, based on commit history "you edited x, and people who do edit y and z"?
- sebdufbeau 4y ago
  Jetbrains IDEs have this feature, however I can't find any other documentation other than this StackOverflow question on how to disable the feature: https://stackoverflow.com/questions/59105219/how-to-get-rid-of-people-who-change-these-files-changelist-in-intellij-ulti https://stackoverflow.com/questions/59105219/how-to-get-rid-...
derrickpersson 4y ago
This is exactly what we're building at https://usecodex.com https://usecodex.com ! We've got an extension on the VS Code Marketplace if you'd like to check us out
Hackbraten 4y ago
> Less "Turns markdown into react components" and more "If you have to touch this, you need to go to file x, add it there" I assume you’re being concerned specifically about the tone and style of your copy possibly coming across as maybe too casual and not professional enough. Please don’t be concerned. A corporate environment doesn’t mean your inline or block comments need to be polished, bureaucratic, or conforming to some style policy. Whoever reads your code and comments is going to appreciate a helpful hint just like you and I would. If I came across a block comment that told me the thing you mentioned, chances are I’d just feel grateful and appreciate the simple, no-bullshit guidance you afforded me.
bsnnkv 4y ago
I have written an internal tool where I work that does this for our DevOps/Platform/Infrastructure repos. Basically, you annotate the code, and the annotation points you to somewhere easy to update (Confluence etc.) where you can add notes about the code. Multiple files, repos etc can have the same reference, so when a CI pipeline runs for a PR on any repo, you get a nice PR comment showing you a tickbox-list of all the other places in the org where this reference exists for you to look at and to make sure you're not breaking something elsewhere, along with a link to wherever observations about this reference are written in prose.
hellohowareu 4y ago
VS Code -> Line Note extension https://github.com/tkrkt/linenote https://github.com/tkrkt/linenote

vmsp 4y ago

There's an Emacs mode that does this called annotate. But why would this be better than just leaving a comment on the file? https://github.com/bastibe/annotate.el https://github.com/bastibe/annotate.el

exdsq 4y ago
Maybe if you’re working on partially open source code you want a layer of comments separate to the code that aren’t version controlled so you can mention internal bits to each other?
Frotag 4y ago
Personally I don't want to have to open the browser to get more detailed docs. I'd rather have it next to the code it's referencing. (Especially if it's just a side project where sphinx or whatever is overkill.)

_boffin_ 4y ago

This isn't explicitly what you're asking for, but it's something: https://plugins.jetbrains.com/plugin/16998-notebook https://plugins.jetbrains.com/plugin/16998-notebook I'm currently thinking of how to do exactly what you described with intellij plugin's. I've realized, that for me, i'm best when i print out code, use rulers to draw dividers between methods and other stuff, and then take notes for different parts of the code. don't mind the horrid writing that's most likely unintelligible: https://i.ibb.co/ByTm7vt/notes.jpg https://i.ibb.co/ByTm7vt/notes.jpg

Frotag 4y ago

I've always wanted something similar to git blame for this. Where I can add notes to sets of lines and toggle whether I want the IDE to display them. Sort of like writing on those overhead projector sheets and saving it to a nearby .notes file or whatever. It'd probably be hell to maintain but a dev can dream. Tangential, but it sucks that it's hard to even find discussion on something like this. Closest I've found is the fictional "an editor" talk here https://www.destroyallsoftware.com/talks/a-whole-new-world https://www.destroyallsoftware.com/talks/a-whole-new-world

aitchnyu 4y ago

Aren't there tools that suggest, based on commit history "you edited x, and people who do edit y and z"?

sebdufbeau 4y ago
Jetbrains IDEs have this feature, however I can't find any other documentation other than this StackOverflow question on how to disable the feature: https://stackoverflow.com/questions/59105219/how-to-get-rid-of-people-who-change-these-files-changelist-in-intellij-ulti https://stackoverflow.com/questions/59105219/how-to-get-rid-...

derrickpersson 4y ago

This is exactly what we're building at https://usecodex.com https://usecodex.com ! We've got an extension on the VS Code Marketplace if you'd like to check us out

Hackbraten 4y ago

> Less "Turns markdown into react components" and more "If you have to touch this, you need to go to file x, add it there" I assume you’re being concerned specifically about the tone and style of your copy possibly coming across as maybe too casual and not professional enough. Please don’t be concerned. A corporate environment doesn’t mean your inline or block comments need to be polished, bureaucratic, or conforming to some style policy. Whoever reads your code and comments is going to appreciate a helpful hint just like you and I would. If I came across a block comment that told me the thing you mentioned, chances are I’d just feel grateful and appreciate the simple, no-bullshit guidance you afforded me.

bsnnkv 4y ago

I have written an internal tool where I work that does this for our DevOps/Platform/Infrastructure repos. Basically, you annotate the code, and the annotation points you to somewhere easy to update (Confluence etc.) where you can add notes about the code. Multiple files, repos etc can have the same reference, so when a CI pipeline runs for a PR on any repo, you get a nice PR comment showing you a tickbox-list of all the other places in the org where this reference exists for you to look at and to make sure you're not breaking something elsewhere, along with a link to wherever observations about this reference are written in prose.

hellohowareu 4y ago

VS Code -> Line Note extension https://github.com/tkrkt/linenote https://github.com/tkrkt/linenote