2

When exploring a new codebase, what would be some methods of storing personal notes or annotations alongside the code? If I were the only maintainer, I might consider added an actual code comment into the code, but doing so in a team would just pollute the code and the git logs.

Ideally there might be something that is not editor-specific, but I'm open to editor-specific suggestions. I personally code in VIM 50% and JetBrains IDEs (With IdeaVIM) 50% of the time. Jetbrains has a Code Notes plugin, but unfortunately that plugin does not work with the current version of the IDE.

Example notes and annotations:

foo = get_foo(bar, boom); // Actually returns a proto-foo, not a foo

foo += 1 // Alice says this is to avoid the lochness bug

if ( !flashing ) brake_light = 1;  // Bob insists on checking flashing in new code even though that feature has been deprecated for 17 years.

foo = processThing(foo); // TODO Figure out what side effects this has

Though I appreciate the reasons stated for committing these specific notes to version control, please appreciate the occasional need for annotating code in a fashion that is not committed into the repo.

Improve this question
8
  • 2
    Why would you not want to put those as comments in the code? Information useful to you is likely to be useful to other developers working in the same code. In particular, the examples you've given here are all things which I would certainly want to know about if I happened to be a future maintainer since they provide what seems to be some relevant and important context about why that code exists in its particular form (e.g. subtle quirk of the code, something which exists to fix a bug, a hidden requirement which isn't documented elsewhere); those are often the most useful comments.
    – Ben Cottrell
    Commented Nov 20, 2020 at 16:49
  • @BenCottrell Thank you. Perhaps the three given examples were not representative of personal notes. I've added a fourth example, which is actually far more typical of the types of notes I would be writing.
    – dotancohen
    Commented Nov 20, 2020 at 17:52
  • doing so in a team would just pollute the code and the git logs I strongly disagree. I think your excerpts are good examples of comments which provide context, and context can be a critical part of understanding business logic in code. All decent IDEs will highlight comments in a different color, which means they shouldn't make the code difficult to read.
    – Dan Wilson
    Commented Nov 20, 2020 at 18:15
  • 1
    Imagine that you get suddenly pulled off that project because the company has a change in strategy. Wouldn't your coworkers benefit from having that comment in the code, as opposed to going through an external set of notes? If my coworker suspects something about a method then I'd really like to know about it. I often wish I could get inside the head of the guys who wrote the service I maintain, but they left the company years ago.
    – Dan Wilson
    Commented Nov 20, 2020 at 18:28
  • 2
    I usually just use a markdown file in the same directory, or, alternatively, keep a directory tree of the form experiments\{username} for people to put any random stuff of their own in. But also wish for what I think you're suggesting: Some way to have personal notes out-of-line from the code yet, somehow, magically, links between code<->notes updated as the code gets versions (so that they point to the same line, or same method, or whatever). Alternatively, some form of lightweight region marking similar to C# #pragma region except with IDE support so you could fold all but yours.
    – davidbak
    Commented Nov 20, 2020 at 18:46

3 Answers 3

Reset to default
3

I'll just comment on your comments.

foo = get_foo(bar, boom); // Actually returns a proto-foo, not a foo

Refactor, rename.

foo += 1 // Alice says this is to avoid the lochness bug

Perfectly good thing to comment. It explain why the code is how it is. And making developer that might change it aware of it is useful.

if ( !flashing ) brake_light = 1; // Bob insists on checking flashing in new code even though that feature has been deprecated for 17 years.

Deprecated does not imply not supported. Talk this with the team instead. Come up with an end of support policy.

foo = processThing(foo); // TODO Figure out what side effects this has

If you don't have a tool that pulls these from comments, it is probably better to just put this in an issue tracker, Kanban board, backlog, or the team preferred method to track things to do. Addendum: If you want to keep it in a private to do list, that is OK too.

Improve this answer
2

I read code with my fingers. So I've always solved this problem by keeping my own local copies of the code that I never publish. Lets me experient and say what's on my mind quickly. Sure it means I have to duplicate some work when I clean up and publish but that's ok.

Another technique is a personal log. I keep notes in one organized sequentially. It can reference into a code base by class and method name, fully qualified if need be. Just don’t ever trust line numbers to last. Do that in a searchable form and you’re on your way to creating your own personal stackoverflow.

That said Ben is right. These example issues are certainly something worth commenting on in the code base. They might need to be cleaned up and talked about with the team. Comments should answer the why question. They shouldn't vent frustration.

Improve this answer
1
  • Thank you wise citrus! Unfortunately I've given three poor examples, see updated question with a fourth example which is better representative of the types of notes that I would be taking. Personal notes.
    – dotancohen
    Commented Nov 20, 2020 at 17:54
0

You could use a documentation tool such as Doxygen. This has tags for common cases e.g. @todo @bugs which nicely collect the tagged comments together in the resulting documentation. Just use use /** to open the comment. You also get some nice documentation if you do this for every function:

/**
 * @internal
 * @param   A   The allocator associated to T.
 * @param   pL  Pointer to the _simple_bt_t to be destroyed.
 *
 * @brief   Destroy a binary tree and free its memory.
 * @return  None.
 * @todo Rerun Valgrind on the test case.
 * @bugs Suffers from the Lochness bug
 */

int i; 

i += 1; /** Hack to prevent Lochness bug on Tuesdays */

etc. Now you get nice web based documentation with all the comments and some files eg. TODO and BUGS with comments and source file details to peruse at your next meeting.

There are lots of other similar apps apart from Doxygen,

Improve this answer
1
  • Thank you Jon. I'm looking for tools to annotate the code, but that would not become part of the code. For instance, a way to leave a "sticky note" near a line of code that I'll see in my IDE, but would not be committed to version control.
    – dotancohen
    Commented Nov 25, 2020 at 16:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.