I couldn't disagree more. TODO is basically an action list you search with grep. When I'm looking for things that could be done, the last thing I want to do is to have to mentally filter out the things that aren't actionable. That just makes the process use a lot more mental energy than necessary. It also leads to unproductive conversations like "we have 147 TODOs, but 18 of them actually need doing at some point, which is an improvement from last month's 123 TODOs with 22 real ones".
No, please, do not do this. As notes, those are wonderful things to add. They're the sort of comments I want to see in the code I'm reading! Keep them! But don't label them as TODOs, for the same reasons that you wouldn't use Reminders as your combined actions and notes app.
Edit: In addition to the mental energy, your brain eventually gives up and becomes blind to them. Then you tend not to see them at all, even the actionable ones, unless you step back and dedicate even more mental energy to mindfully going through them one at a time to give them a fair reassessment. This gives me more ADHD-fueled anxiety than I can describe.
It's a bad thing if you're using the same tag for "we need to change this" and "this is something we might eventually consider". Imagine looking in your bug tracker and seeing a thousand tasks with no differentiation, no tagging, no priority marking, and trying to decide what to do next.
Only things that are genuinely actionable should be marked as actions to be done. If it's just something you'd like to clean up, eventually, given infinite free time, label it as a note. Otherwise you're blowing up the amount of information you have to sift through when deciding what work to do.
I'm not sure you're disagreeing with the post you're replying to?
I tend to use FIXME for things that really do need to be fixed, and will not push code containing a FIXME comment. Grepping for FIXME is useful.
I tend to use TODO for things that I'm thinking may be useful, but aren't necessary (yet). Sometimes it'll be "TODO: Figure out whether..." or "TODO: Validate this by measuring the impact, to see if it'd be better to do something more complicated or simpler." I could rewrite all of these as regular comments -- the latter might be "I have not validated the assumptions here via measurements; something simpler might be good enough." But the TODO is a little more direct. Grepping my code for TODO isn't that useful. (Well, save for the comment block at the top, where I tend to leave actual todo comments, but they're still future tasks not FIXME-style "do this before landing" tasks. And I label them with [ ] checkboxes, not "TODO".)
So we agree: don't use the same tag for both. It sounds like you use TODO for "we need to change this" and I use FIXME for that. I suspect we all have a broad range of labels: TODO, FIXME, NOTE, plain comments, comments linked to bugs, etc. When reviewing teammates' code, I check whether their TODO comments should have a bug link, should not say "TODO", should be removed entirely, or whatever.
I don't disagree with any of that. But we're talking in the context of this article, which includes 2 example comments:
// TODO: Write the second half of this file so next week's launch won't explode
then sure, you should probably track that somewhere.
and
// TODO: If the user triple-clicks this button, the click handler errors because [xyz]
So my comment is also in that context of using the same tag for things of wildly different importance and urgency. And that would drive me to drink.
Definitely come up with a local convention for which tags mean what, and pick whatever resonates with your team. TODO in your org can mean something different from mine, and that's perfectly fine. Just please, please use different tags for different things, as you're recommending.
I was just given a bottle of Booker's Bourbon, batch 2023-01 (https://www.bookersbourbon.com/bourbons/2023-01-charlies-bat...), but I haven't gotten the nerve to break the seal yet. Or since receiving it, had a day wonderful enough to justify celebrating with it, for that matter.
Later: FIXMEs aren't for doing. FIXMEs are comments describing how a piece of code is less than ideal. The code works, of course, because we never commit non-working code -- it could be improved, but it's not broken. The actual fix me is a compiler error.
Later: some compiler errors are just warnings. If you really know what you're doing, you can suppress them and go about your merry day. You're not paid to make correct code; just "shippable" code.
Anyways, I'd be happy with a structure like
- "NIT" that acts more like notes for correct implementations used for highlighting potentially better structures or optimization to consider farther down the line
- TODO for issues that can or will become issues later on, but are otherwise functional for prototyping purposes. I don't think every TODO needs to be corrected, but you should have a refactoring day every period where you address most of these TODOS.
- FIXME for critical or showstopper level issues, but you need to clock out for the day. There shouldn't be any FIXME in a stable branch of code. Arguably a FIXME shouldn't persist for more than a few commits.
My code contains no NOTEs,TODOs,FIXMEs or Comments, for as Programmer, I have transcended space and time to the final abstraction, and no longer write any code, only long complicated manual procedures, which I then outsource to third parties, who in true programming fashion use AI.
//TODO: change the downstream code so it's less brittle after we get to prod(WARN)
//TODO: don't hard code this variable, had to get prod up and running due to leap year
In my experience TODO are most commonly placed by either the guy doing a greenfield project, the code maintainer, or the guy getting production out of the ditch at 2am on a Saturday. I don't think I've ever seen a junior dev write one. My code has a few TODO sprinkled in but they're fairly rare, and call out where I had to make a decision due to constraints, and inform which direction I intended to take.
They're placeholders for me. Not for everyone else. I can't write perfect code the first time. I may use hardcoded strings (instead of spending 20 mins uploading the string to localization). I may make a O(n^2) loop because I'm fixing another problem. If you find these TODO in a PR, you should call them out. Or I might be on a long vacation next week but I don't want to leave the branch out of sync for a long time and it works but is a little dirty.
In some other cases, they don't have to be done now. They're bottom priority. A hardcoded color that won't work with dark mode, but we have no plans to use dark mode, etc.
Personally, I normally don't. But every now and then it just intuitively seems like the right way to phrase the comment. Afraid I can't really explain any better than that.
It's useful when an unrelated change unintentionally gets rid of a TODO and you can cross-reference it with the tracker item to see more context and maybe close it too.
I like the idea presented by the author. This is because, in my opinion, classic TODOs have no place in the main branch. You can do whatever you want in your feature branch or on your local machine, but not in the shared codebase. If something is not ready, you are not done, and you should not commit or merge it.
In my opinion, the author describes more of a NOTE, such as, "Currently, we support X because of the requirements in TICKET-X. If you want to support X and Y..." or "This was done like this because of X. The better solution is Y and it make sense to do the better solution when ...". I like the idea of helping my future self quickly understand why something was done in a specific way and how I can refactor it now. Also this indicates that how ever added the NOTE, is a good software engineer, that does not implement features or functionality that is not needed yet.
Code coverage is another, but some numpty always gets it in their head to go for quantity over quality and they introduce coverage that doesn’t test shit. I will spare you my rant about how 85% is the optimal code coverage.
> Most users won’t end up triple-clicking that button.
Absolutely they will. If they're on slow enough network speeds, they might get frustrated and start tapping / clicking away. I grew up on Dialup internet, I remember the struggle.
No, please, do not do this. As notes, those are wonderful things to add. They're the sort of comments I want to see in the code I'm reading! Keep them! But don't label them as TODOs, for the same reasons that you wouldn't use Reminders as your combined actions and notes app.
Edit: In addition to the mental energy, your brain eventually gives up and becomes blind to them. Then you tend not to see them at all, even the actionable ones, unless you step back and dedicate even more mental energy to mindfully going through them one at a time to give them a fair reassessment. This gives me more ADHD-fueled anxiety than I can describe.