I much prefer either
- TODOs are resolved before merge (your FIXME)
- TODOs are moved (not copied) to the team backlog (maintaining in both places just gets them out of sync)
- TODOs are converted to documentation explaining the approach (e.g. HACKs)
On the contrary; since they are right next to the thing that needs work you always encounter them Just In Time. And you can just delete them really easily if you decide they're truly stale. This may not lend itself to planning or management visibility, but for a small private project I prefer them to the overhead of separate tracking.
For a small private project there's no organisation which doesn't work.
I don't have anything resembling an issue tracker, but I've begun collecting brain dump style notes in either a gist or the Apple notes app.
Some of my side projects have more process around them than my work projects because the side projects will definitely get shelved at some point and resumed much later. Future me is always happier when the process was applied.
That means they become scenery, not something in the foreground. They are lost.
- Create ticket in team backlog and add ticket number to TODO comment (and have CI pipeline check that ticket number is valid)
Say you do get past that hurdle, you've added friction to the process of managing the backlog because the code now needs to be updated when Issues are rejected.
The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue.
Makes perfect sense. TODOs are comment, meaning they're as reliable as comments, meaning they often aren't (and the more time passes and code churns around them the less they are).
Clean the code, comment actualities later, etc. -- it helps with knowledge share to find ways to make you attend to cleaning things up.
I also sometimes include a stricter version that includes a test for the current behavior, on the theory that someone changing the current behavior might be in a good position to fix the ticket.
I don't understand that use case.
Do you mean that if you set the envvar, the test now becomes "normal" because the assumption is you're trying to fix the ticket, and thus make the test pass?
I guess that makes sense if your workflow is to "clock in" on tickets, to which you can hook env updates?
I still tend to keep the "HACKS" thing though, simply because they localize the documentation right where you need to be aware of it.
Is the use of HACKS just to highlight the importance of a comment? I tend to just stick those in a regular comment. Or if extra important NOTE at the beginning. For instance I refactored code the other day forgetting why it was the way it was, it didn't work, and then made a NOTE for it so I don't do it again.
For "DREAM" there is a ticket for proper tracking. For FIXME, code review prior to merge is sufficient. For HACKS, you really only need to care when you happen to be working in that space.
And yes, HACKS is to highlight the importance of a comment. It also signals an intentional deviation and an opportunity for someone to offer a suggestion on how to improve things.
- // STOPSHIP: the presence of this string anywhere in the codebase causes a production build to fail.
- // TODO: for everything else.
Once you're reaching 1.0.0, you know these can no longer be sliding through, and you can support all of this in CI.
Edit: I just added this into my editor but it's not highlighted by default. I wonder if there's a way to highlight it.
There, fixed it.
[1]: https://marketplace.visualstudio.com/items?itemName=ExodiusS...
- DREAM tags let me focus on getting things shipped and avoid over optimizing/generalizing things that won't provide immediate value. When working in a professional context, they are always accompanied by a ticket. This adds a nice binding for whoever comes next to pick up the task.
- FIXME is also used to help maintain focus, but with the rule that no code ever gets merged with this tag still in place. For personal projects my branches tend to be quite large, so I'm comfortable accumulating some small number of these.
- HACKS calls out unintuitive behavior: breaks in abstraction layers, worst-practices that have better implementations than best-practices, or anything that smells "clever".
Everything else is just comments that future me/team can look back on and say "he must have been drunk when he wrote this, but thanks to these comments I can clearly understand the context and at least what was intended."