DEV Community

loading...
Cover image for How do you keep track of notes in code?

How do you keep track of notes in code?

madza profile image Madza 惻1 min read

Keeping track of notes while coding is essential, so you have all the ideas for development once you re-visit. Thanks to code commenting and various extensions, you don't need to leave your code editor / IDE for that.

Some of the methods I am aware of include:

  • Making comments on top of the file, adding them in the list once an idea strikes. (Ctrl + /) is a useful shortcut for that in VS Code.
  • Using extensions like Better Comments and TODO Highlight to make comments in different colors, so it's easy to distinguish between to-dos, warnings, highlights, questions, etc.
  • Using Todo Tree to create a tree of todos across multiple files, displaying them in the side panel for a great overview and easy management.

How do you normally approach this?

Discussion

pic
Editor guide
Collapse
bpedroza profile image
Bryan

I absolutely loathe seeing TODO in any comments in code. If you know you need to do something, just do it. IMO, these can be tracked with source control. If I see a TODO comment in the PR, it's not getting merged in. Open an issue if you're not going to do it now so others can track it, or tackle it.

Sorry, I know this probably isn't the kind of feedback you're looking for, but it's how I feel about it.

Collapse
madza profile image
Madza Author

I see where you are coming from šŸ˜‰ For collaboration oriented projects I prefer using the issues panel too, for personal projects I like to make notes directly in code. Nothing will be deployed to production, while there are still to-dos left, I just find this approach more productive as I don't have to switch between any notes app šŸ˜‰

Collapse
bpedroza profile image
Bryan

I can see that use case. I know some people have pointed to IDE extensions to track these. I think a clearer way to do this while in development is just to write a failing test. Example in php:

public function test_can_upload_file()
{
    $this->fail('Upload file functionality needs to be implemented.');
}
Enter fullscreen mode Exit fullscreen mode

This way it's clear something is not done when running your test suite and you don't have to change your development practices to go hunting for them. Run the test suite -> see tests are failing -> there are things to do.

As with anything in programming though, that's just my opinion šŸ˜„

Thread Thread
madza profile image
Madza Author

from the programming view, this is absolutely correct and should be considered as a best practice šŸ˜‰ i know it's just me, usually being too lazy to write failing tests, when you could do just Ctrl + / šŸ˜‚šŸ˜‚

Collapse
1e4_ profile image
Ian

If your working on something else or it's end of day on your own branch it makes sense to use @todo with a comment. I agree however there should not be any @todo in any branch in production

Collapse
bpedroza profile image
Bryan

Yeah, totally agree.

Collapse
dansilcox profile image
Dan Silcox

I even have a pre-commit git hook for this - well, to be fair, I allow the TODO to exist as long as there's an issue reference to go with it :D

Collapse
bpedroza profile image
Bryan

That's an interesting idea. I'd be curious to see what that looks like if you're able to share.

Collapse
yoursunny profile image
Junxiao Shi

I have a stack of recycled paper (i.e. one side already used) on my desk. I write my ideas on the blank side, with date and project name and module topic on the top line.
When I finish a feature, it feels satisfying to feed the page into the shredding machine (nothing confidential but the sound of the shredding machine celebrates my achievement).

Collapse
madza profile image
Madza Author

Hats off for this approach, I've always believed that resources should be used efficiently too šŸ‘

Collapse
yaser profile image
Yaser Al-Najjar

I tried TODOs and they're not the best approach, just use GitHub issues... it will save you from distraction, headache, and ugly code.

Collapse
dailydevtips1 profile image
Chris Bongers

I mainly log issues in our work board (Trello based)
Then will make the comments in the code with Better Comments VS plugin.
And will do some Todo's, but still looking for a good way there.

Collapse
madza profile image
Madza Author

I love Trello too, I use it for more general stuff, like project ideas and so on šŸ˜‰

Collapse
quantalabs profile image
QLabs

To be honest, I don't use TODOs. When I find a bug, I go ahead and fix it, instead of just waiting for tomorrow and procrastinating.

Collapse
baptistecrouzet profile image
Baptiste Crouzet

Better comments <3

VS Code bookmark extension is good too !

Collapse
programmerbyda1 profile image
ProgrammerByDay

I would create a story in the backlog for that. Code should be as clean as possible.
The only time Iā€™d suggest to put a todo is when there is a piece of code that may not make sense to other devs (eg throwing an exception instead of the actual code), in this case you can put a small todo comment and write the story number that is related to here. (Eg throwing exception until story 114 is implemented)

Collapse
brandsofttech profile image
Brand Soft Tech

Thankku for sharing this ammazing content its to much helpful
i am founding this blog for a long time after a long time a find your blog thanku sir your content is so helpful for me & all
inpage urdu