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.

> So my comment is also in that context of using the same tag for things of wildly different importance and urgency.

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.

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.

Soon, though.

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.

Whatever theme/packages I use in Emacs have been highlighting NOTE, TODO, FIXME in comments for at least the last 10 years, so that's what I use.

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.

NOTE is a good word for it too. Never saw it in the wild myself, but I'll adopt that (easier than explaining what NIT is)

You don't need to be accused of being a nit-picker all that many times to figure out what a nit is.

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.

I tend to put my real action list in a separate document, not in version control....

But then why label things with TODO in the code, if they're not really things you intend to do?

It's similar to logging INFO vs WARN.

//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.

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.