"your brain eventually gives up and becomes blind to them."
This is not a bad thing if they are not for doing. They're there to mark that the code is incomplete but not broken. The actual to do is a FIXME.
This is not a bad thing if they are not for doing. They're there to mark that the code is incomplete but not broken. The actual to do is a FIXME.
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 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.
// TODO: Write the second half of this file so next week's launch won't explode
then sure, you should probably track that somewhere.
// TODO: If the user triple-clicks this button, the click handler errors because [xyz]
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.
Ah, ok. That's fair. I agree that the example comments ought to be considered different categories. That first one is a TODO that is for doing.
> And that would drive me to drink.
Is that a bad thing? It depends on what you're drinking.
Soon, though.
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.
So the label is kind of useful: for flushing out the people who need it explained -- now you know sho's sloppy enough to be worth being wary about.
//this is an info level comment
//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.
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.