[basfo]

The example in the article:

> // TODO: If the user triple-clicks this button, the click handler errors because [xyz]

looks more like a comment than a real TODO to me. I agree that comments like those are useful, but shouldn't be a TODO.

A TODO implies a specific type of comment. One that implies a task, points to something that should actually be done (like TODO: This function should return another value with XYZ). And I agree that the proper place for that is a tracker, not buried in the code.

In the example just documents a bug. , there is no actual action.

In my experience, TODOs are often a way to get quick and dirty code approved in a PR. They usually never get done, they're just a way to push the responsibility onto some future developer who "will have more time" (which means it will likely never happen).

[sophiebits]

Comments are usually for explaining why code is doing what it’s doing. If you write just

// If the user triple-clicks this button, the click handler errors because [xyz]

then it’s less clear at a glance that this behavior is undesirable. Is this a bug, or is it supposed to be this way? “TODO” is a quick marker that (to me) means “here’s something that is not ideal and may be worth keeping in mind if you are working on this code”.

If you or your reviewers know that it’s not OK for the fix to never be implemented, then of course, track it somewhere where it will get done. My experience is that discouraging TODO comments leads to less-documented code, not better code.

[kstrauser]

I think that's a case for "NOTE", which has the semantics of "this is something unusual and significant to pay attention to".

Edit: BTW, my specific disagreement is with using "TODO" to mean different things. I'm otherwise completely on board with the kinds of comments you're asking people to write, even if I'd label them differently. When I'm trying to understand new code, much of the effort is in trying to figure out why the author chose the approach they did. Why'd they do this instead of the more usual approach? Did they understand the tradeoffs, or just find things on Stack Overflow or ChatGPT? Did they take this edge case into consideration? Seeing their thinking is vastly more useful than

  // Add two numbers
  three = one + two

[muzani]

It's a skip. Most are fine even if they never get done. What's not fine is when code is not fully functioning and we assume it is.

My favorite TODO was something like class EncryptedSharedPreferences with a "TODO: encrypt this". It was written by someone who left before I joined (I never would have approved it lol). But it made it clear that this code was indeed, unencrypted, instead of having to figure out whether it was encrypted by some other module or worrying that we'd encrypt it twice.

[zahlman]

Surely it's the data that needed to be encrypted?

[_9ptr]

No, the comment.

[WatchDog]

The example seems like more of a FIXME than a TODO.

It’s a clear error, but likely unimportant enough to bother addressing.

[SoftTalker]

I dislike that as an example of a "good" TODO comment because for the same effort as writing that comment you could just fix the issue, or at least make it do something that isn't an error (and then maybe leave a comment such as "triple-clicks ignored because [xyz]).

You've already gone to the effort of determining the trigger and the reasons for the error, so you're probably 80% there.