As a proponent of "TODOs should always point to a concrete issue", you have 3 ways to resolve a TODO before merging:

1. Just file the issue. If it's something you should actually do, you can take 20 seconds to write it down and track it. 2. Just do it. If it seems like too small of a thing to file an issue for, fix it before you commit it. 3. Turn it into a comment. If it's not worth fixing and not worth tracking, but you want to remember it, that's a fine thing for a regular code comment.

Eat your broccoli. Track your todos.

I add and grep for the following:

- FIXME: this is clearly broken/wrong and highest priority

- XXX: this is “ugly” or assumes wrong things, probably higher than next

- TODO: at some point, implement a whole different approach/category/branch

- NOTE: code comment with a higher importance than just random comment

NOTE: I work a lot with old/unmaintained codebases where “code is truth”, so there is no “jira ticket creation” but amending things as you read.

To me this brings the phrase to mind: "perfect is the enemy of the good."

Ideally tech debt or code-smell encountered like this would be captured/tracked/described better but often-times this means context switching or engaging in some kind of high-friction activity (like filling out a JIRA ticket) and that just discourages tracking it at all. At least inline TODOs are captured somewhere. And they can be for doing.

This is a style issue. Different people can have different definitions and cultures around TODOs.

My codebases tend to use TODO exactly as described here. A TODO is really just a comment documenting the implementation -- specifically, documenting something that is missing, but could be useful. It doesn't mean it actually needs to be done.

IMO it doesn't make sense to use comments in the codebase itself as an actual task list, because priorities are constantly changing. Things that seemed important when you wrote the code may turn out not to be, and things that you didn't think of when writing turn out to be needed. Are you constantly submitting PRs just to update the TODO comments to reflect current thinking? I mean, sure, I guess you could do that, but I think it makes more sense to maintain that list in a bug tracker or even just a text document that can be updated with less overhead.

Title is a little click-baity but I fully agree with the sentiment. Just minutes ago I had this experience where a #TODO marked out some extremely rare edge case to handle but one that I have never seen actually occur in the 2 years since I put it in there. Still it will be useful to others (and future me) when I look back at the code and wonder why something wasn't handled.

I also agree with users that sometimes these should just be comments. Really depends on your environment and since I work on a team of 2 who maintain my portion of the codebase I stick with using TODOs in this way (seomtimes).

Agreed - there needs to be a space for known issues that are not worth tracking. Issues that need to be understood as real, but perhaps may never be viable to fix. Something you can ctrl-F for when you have time and are curious if there's something you can clean up.

It drives me insane that so many tools/processes treat TODOs as essentially code smells.

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

Strongly agree. I think of TODO as a task that might be interesting for the next person who stumbles over this code. "This logic is not great. If you happen to refactor this entire feature consider changing this thing as well". The TODO can even have an associated ticket but because it's right in the code it's more discoverable. Otherwise, the next person to change the code might even complete the ticket without knowing it.

I also use a tiered strategy and FIXME for things that really need to be fixed or I have a solid idea what the next step would be to fixing it.

TODOs are something less solid than a FIXME and are also just about getting it out of your head so you can devote more mental energy to something else or just relax.

Maybe the idea is not fully formed yet, maybe you are not sure you really want to do it, maybe it is waiting on something else, but it needs to be captured or you will have to keep thinking about it lest you forget.

As soon as I write down a TODO (code or other) that was only in my head, I can relax a little more, because now it's captured for future reference.

Hard disagree. If you're not going to file a bug or ever do it, don't write TODO

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

This is documenting what currently happens. It's not TODO, and that word shouldn't be in the comment.

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.

This short article is not about TODOs, it’s about good comments, in general. Any comment that gives you context about edge cases, about why some decision was made, about why other approaches went wrong is great!

I would argue TODO means “intent to implement”, and they should be regularly converted into either tasks, documentation or just standard comments without a special keyword.

I see comments as a failure of my prose capacity at coding. I try to commit code that should be able to explain itself as if it were accompanied by any comments. But if something is too confusing to be maintained by someone else (like me 6 months from now), then I use a comment. But that is a sad moment because I also know that this future person can update the code and not update the comment, then the thing becomes even more confusing. TODOs should never be in committed code; they should live in your project/issue management system.

Interesting, yesterday I was looking at the source code of some library, and noticed a lot TODOs scattered all over. At first, I thought it's a red flag and I shouldn't use this library.

However, once I read them all of them, were exactly this: very rare edge cases, minor optimizations, and notes about future optimizations possible optimizations.

I pretty much immediately adopted this style of todos.

Then maybe those todos are not todos but just regular comments?

I love this TODO approach not just for what it does for future readers as Sophie notes but also for the mental release it gives me when thinking about edge cases that I don't want to commit to fixing.

PS Hi Sophie!

I think this is fair. Untracked TODOs should be minimized but I think there is value in recording how some section of code could be improved even if you know you are unlikely to do it. I don't think the triple click thing is a good example because that seems like a bug to me.

An example from my codebase is that I implemented a daily scheduled job that may display inconsistent results during short time per day it is running. Realistically fixing this will never be worth my time, this is a transit app and it is scheduled to do this at night when the buses aren't running and it will only be inconsistent if they change the schedule after already publishing it for a given day which happens pretty much never. It is also a personal project with no issue tracking.

Eventually I will rewrite this loader logic to support multiple transit systems so it is good to have my notes of how I would do it better next time. Also, if this does result strange schedule behavior I would immediately go to this file and see my explanation of the flaws with my approach. Maybe I shouldn't call this a TODO but it seems like a good fit.

For that reason I’ll often prefer the word REVISIT instead of TODO. Kinda less obligatory.

I think there are lots of valid ways of using TODO comments.

In my org, TODO comments trigger the linter, so they usually have to be addressed, downgraded to a regular comment, or turned into a ticket. They're a nice way for me to mark places I need to remember to come back to before I put something up for review.

I sympathize heavily with the viewpoint that pushing these things into ticketing systems means they're less likely to get done. I think it's nearly impossible to lobby for TODO: comments to get done against a never ending stream of ultra important high business value work. Leaving these concerns inside of the codebase itself is one way that programmers can take back control when technical concerns and code quality are dismissed or deprioritized constantly.

Replace the not-TODOs with NOTEs.

For example, this TODO:

   //todo: factor this out in case X

Because if X ever happens, the note won’t matter anyway, since you will have had to grok all the related code to refactor. You will see this note while you’re refactoring the surrounding code and smirk, “yep, that’s right”, or “no, it doesn’t really fall out that way.” Either way, most TODOs/NOTEs like this just get in the way.

TODO: Action item that must get done at some point.

TODO? or ?TODO: Documenting funky code that the developer can't triage at the moment without losing flow state but is "off".

Instead of a separate MAYBE any action should have an indicator of confidence level.

We are marking the developers intuition about something they have run into, human intuition is both important and fuzzy, we should mark it as such.

The more ? the fuzzier it gets.

Humans have a bunch of symbols in their brains, we may disagree about the symbols usage but if a developer has a small thought about a codebase let them get it out quickly and with clarity.

The real problem is that unified tooling for plaintext editing and zoomed out team project management don't have a good interface that let's people notate with the level of friction commiserate to the importance of the notation.

OP, have a look at todo tree: https://github.com/Gruntfuggly/todo-tree

it's a game changer while solo or on a team. and I’m sure it's reproducible outside of vscode (it's just highlighting depending on the todo token used).

been using it and introducing it to teams for years. it's even more helpful now with AI.

Fwiw i’ve see far fewer todos lately since LLMs have gotten significantly better as of late. The todo documentation is often a perfect prompt.

Introducing TODO.ai where we handle all your todos for you

Maybe I'm strange but I'll throw TODO In my code as I'm working through it, usually alone the lines of "double check the chain here later"

When I'm then doing my final commit I'll do a search and check them off.. Theyre incredibly useful. I use pen and paper too but they go missing

This is just going to lead to things not being done as nobody knows whether or not the TODO is resolved or not.

Personally, I tag my comments in one of two ways:

1. // TODO: <task> (if multiple things, I do a multiline comment with Markdown-style checkboxes next to each item in the list).

2. // NOTE: <explainer>

The former is what you'd expect (I routinely search for these to make sure I'm not missing minutiae) and the latter is for code that can't be refactored to make it clear and requires some explanation.

Doing this consistently has really saved my bacon over the years (both in terms of keeping track of tasks and remembering why I had to use that ridiculous chunk of code to get something to work).

But the second example there shouldn't be a TODO then, but just a NOTE (or regular comment).

For cases like the one described in the article, I prefer NB comments.

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

I've certainly overdone it.

When I left a job after many years, my collegues printed a listing of all my // TODO(pht) .

It was big and full of things that never got "TODONE".

My personal philosophy is that TODOs should only be used while working on a branch. Once its ready for a pull request, any pending TODOs should be abandoned or logged in an issue tracker.

My whole thing here is that this is just as effective of a comment without the todo prefix.

Lint the TODO part before merging, then TODO becomes a nice thing you can grep for on your own branch, like a note to yourself.

sometimes I use todod for regex search and replace to refactor later. like to mark all the places where I want to later change the logging level, but for now I want to info log the query headers.

I have three levels:

1. An issue tracker, even if it's just a text file for some projects. These are things that need to get done over the long term.

2. TODOs. These are actually bugs or incomplete things. The code is not actually done. Something isn't handled, something isn't right. Big or small, but usually small.

3. XXXs. These are performance enhancements or refactorings. It's XXX because it's obscene that this code looks this way, because it's either ugly, slow, or gross. But the code works and is tested.

// TODO(<issue-tracker-id>): <Short description>

This format allow for quickly finding the place where the thing needs to be done, while keeping track of the issue in the issue tracker.

I often write the issue tracker ID's in my code to add additional context. It works especially well for bugs which are reproducable in programatic tests. Then I name the test specification after the ticket, so that it's known that this bug doesn't resurface as regression.

I have a similar philosophy for low priority tickets. Some people say it's not worth filing a low priority ticket since we can't even do the medium priority ones. I think it's still valuable since (1) it let's you write it down to remove it from your mind, and (2) you can track repeated instances or anything else that might cause you to increase the priority.

I think TODOs are great for refactors you cannot start right now.

It's very local, this code should change but it might not be possible during the timeframe I've been given.

For future reader it might give hint what to change or what is wrong here.

They capture information you have when writing the code that communicates something useful about it.

> Ehh, maybe I’ll just leave it the way it was in case the original author knew something I don’t.

That's probably the main point of code comments in general: to explain to the future reader or maintener (who may be your future self) why things are the way they are.

My policy: If it's a real TODO, it includes the ticket number/link tracking the actual fix. Otherwise it should either be a regular comment or not exist.

This article should expand more on what TODOs are actually for, in that case. What's the difference between a regular comment (which is what the example in the article clearly is) vs an actual TODO comment?

Second todo isn't a todo, should be a trade-off comment. Something like "Technically, this will raise an error if the user triple clicks the button, but most people ain't that fast, so screw it"

I have never seen TODOs being cleaned up in enterprise environment. Therefore our team would not approve PR with TODOs: either fix them yourself or open a separate ticket for it.

This is a great example of a practice that is pragmatic and smooths the way for future polish if the software grows in usage by 100x, without investing a bunch of effort now that won't make sense if it doesn't grow (and might stop you from doing the things that will enable it to grow.)

If usage takes off by 100x, someday somebody will be tasked with clearing up errors in Sentry (or whatever) so bugs and regressions are easier to spot, and this comment will save them hours of debugging.

However, I think using TODO to flag it is a poor choice. Good luck explaining to your teammates, "We use TODO to communicate that we aren't going to do something." I doubt you're going to get consistent adherence to such a counterintuitive convention. Instead, I would prefix the comment with "KNOWN ISSUE."

If it's not intended to be done, then you are using the wrong name. Don't call it `TODO`.

In my code these days, I have:

TODO

SHOULDDO

COULDDO

The TODOs generally don't make it to main, the others sometimes get picked up eventually.

for the laconic and latin-familiar, NB stands for nota bene, or "note well".

for the laconic and latin-leaning, NB (nota bene) means "note well"

TODOs are a code smell.

If there's a known unhandled edge case there should be conditional logic guarding against it.

If the original author dislikes the idea of a refactor... well too bad it's not their decision anymore, but they should have at least been kind enough to write tests.

I have 2 kinds of TODOs in my code:

// TODO: optimize something, refactor, blah ... // TO_F_DO: this thing is gonna blow up, can't fix it now but do it ASAP

TODO - when I have nothing to do I browse those, pick the on I like and do it.

TO_F_DO - if I find more than 1 in my code I am suicidal

If a TODO is not for doing, it should be recorded as a NOTE, documenting the limitation instead of the task.

If your TODO isn’t actionable, I’m deleting it. Too bad. Bury your skeletons elsewhere.

It seems pointless to write "TODO" if it's not, you know, to do. Yes you should write comments describing ways the code can be inproved, but those can just be comments that don't confuse other people, not to mention trip all sorts of code highlighting and automated checks.

What? What's 'TODO' about the second TODO in the article?

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

That could be a simple comment, but if its a TODO it should be ´TODO(bug/<id>): Fix triple-click error in this button´.

If you really want to tag a normal comment, what about // NOTE?

I think some of the TODOs are used to silence programmer's guilty conscience and protect their reputation in the eyes of future maintainer (which might be their colleague): "I know this code sucks, and this is how it can be made better, it's just my PM was pushing me to finish this task ASAP"

Off topic, what did the detective say to the developer?

  TODO, TODO, TODO TODO TODO TODO TODOOOOO

Ok fine, how do you track completed TODOs?

  With TADAs!

  // TODO: Find better material

I rarely find reasons to disagree so much with anything I read like I did with this blog post. Seems like the author lacks rigor and then goes looking for ways to excuse being sloppy, that's an attitude I don't think is productive or creates anything positive in the industry.

> But the `// TODO:` doesn’t need to be a plan to actually do something. Instead, it’s a note about “here’s an edge case that wasn’t handled” or a suggestion for a better structure that the author didn’t make time to implement — it captures a little slice of the author’s brain and gives a little window into the rich context they had at the time they wrote the code.

Sounds to me like this should just be a regular comment. Don't add "TODO" if you're not actually going TO DO it.

When I have a thought about how some piece of code could/should be improved, but it's not urgent, instead of

  // TODO: Refactor this by doing X, Y, Z

  // Hmm: This seems brittle.  We might want to X, Y, Z this such that W.

WTF is "TODO?"

Step one is: learn English.

great post