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.
Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished. Issues in an external systems may also be overlooked by developers working on this particular code.
There are plenty of small things that are worth fixing, but not worth as much as the overhead of tracking them.
TODO in code is easy to spot when someone is working on this code, and easy to delete when the code is refactored.
I think the key distinction is that tracking in an external system exposes the task for triage/management/prioritization to people who aren't reading the code, while a TODO comment often leaves the message in exactly the spot where a programmer would read it if the possibility of a problem became an actual problem that they had to debug.
In my experience, these can often be replaced with logger.Error("the todo") or throw new Exception("the todo"), which read about as well as //TODO: the todo, but also can bubble up to people not actually reading the code. Sometimes, though, there's no simple test to trigger that line of code, and it just needs to be a comment.
> Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished.
Which is already what you're doing in that system, and what the system is designed for.
Source code is not designed to track and management issues and make sure they get prioritized, so you shouldn't be using your source code to do this.
We add TODOs during development, and then during review we either add a ticket and remove the TODO, or fix the issue as part of the PR and remove the TODO.
> Source code is not designed to track and management issues and make sure they get prioritized, so you shouldn't be using your source code to do this.
Indeed. Who in their right mind would think it is reasonable to track relevant tasks purposely outside of a system designed and used explicitly to get tasks done?
Also, no one prevents a developer from closing a ticket before triaging it. If you fix a TODO, just post a comment and close it. I mean, will your manager complain about effortlessly clearing the backlog? Come on.
This gives me an idea for a source control/task task tracking system where TODOs in code get automatically turned into tickets in your tracker, and then removed from your code automatically.
That way you don't fill your code with a list of TODOs and you'll still be able to track what you want to improve in your codebase.
It might not be the right tool for everyone, but I'd love it.
You can leave the TODO in the comments- e.g. ruff the linter has an optional rule to disallow TODO comments unless it's followed by an issue url.
If you put that in the CI, then you can use TODOs either as blockers you wish to fix before merging, or as long term comments to be fixed in a future ticket.
Some years ago, I started to use FIXME to indicate that something is blocking the PR and needs to be done before merging, and TODO if something can be done at a later point in time. Then, CI only needs to grep for FIXME to block merging the PR, which works for practically any language. Works pretty well for me, maybe that tip can help others as well.
> Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished.
Filing the issue can take as long as writing the TODO message.
Triaging it, backlog management, re-triaging to see if it's still a problem... It's called working on the issue. I mean, do you plan on working on a TODO without knowing if it is still a problem? Come on.
> Issues in an external systems may also be overlooked by developers working on this particular code.
I stumbled upon TODO entries that were over a decade old. TODOs in the code are designed to be overlooked.
The external system was adopted and was purposely designed to help developers track issues, including bugs.
You are also somehow assuming that there is no overhead in committing TODO messages. I mean, you need to post and review a PR to update a TODO message? How nuts is that.
> There are plenty of small things that are worth fixing, but not worth as much as the overhead of tracking them.
If those small things are worth fixing, they are worth filing a ticket.
If something you perceive as an issue is not worth the trouble of tracking, it's also not worth creating a comment to track it.
Todos can also serve as a direction where you want the code to go to. Leaving this in the code ensures everyone working on it sees it, and every change they make can take this direction in mind.
Maybe THIS change finally warrants implementing foo, or at least refrain from implementing bar.
I think the author is basically arguing for #3 but not addressing the difference between a `TODO` comment vs. a non-`TODO` comment.
I guess the `TODO` terms has a certain visual flair that makes us immediately understand the class of comment. I guess that would be my best argument for keeping it a `TODO` comment instead of a regular one. But when you see the author arguing that `TODO` comments dont mean you need TO DO anything, it's kind of a smell, isn't it?
I find myself generally agreeing with the article's sentinment but think your option #3 of just making it a non-TODO comment an improvement.
Rider definitely has a popup with a list of TODOs before you push to the remote. I assumed that originally existed in intellij... but never verified that.
I was just having this conversation with myself for another reason this morning (trying to define why automating processes is a force multiplier and mistake reducer). Because there’s little to no IDE integration for ticket tracking, swapping to the ticket system is a context switch. And the ticket system has ways of demanding your attention once you’re in there. If it succeeds now you’re pre-empted.
The thing about concurrency is that as long as you don’t know about a priority message you can continue to make progress on the task at hand. The moment you are aware of it you have to deal with it or have to explain yourself later. “I didn’t see it” goes a lot farther than, “I did but I was busy.”
My ex would try to check her work email on a Friday evening as we were on our way out the door for a trip out of town. A trip her boss likely knew about. That’s not why she’s my ex but it certainly didn’t help. That email arrived after you already left, lady. That’s your story and we are sticking to it. Don’t go looking for conflict, particularly when doing so affects people other than yourself.
Make the bar high enough and people won’t bother to do either and instead just hope for the best or keep their own list of TODOs elsewhere.
The point of a cheap informal method is to as low of a bar as possible so that more information is collected. As for always immediately fixing that’s the same as making everything the top priority, the true priority is lost.
Too many TODO comments and not enough tracked issues, that’s a sign that issue tracking has too much ceremony. Ban the use of TODOs and you lose even that information.
Perhaps a codebase could be watched such that new tracking issues are added and tracked implicitly when checked in by searching for new TODOs in the code. Similarly the tracking issue could be closed when the corresponding TODO is deleted from the code.
Jira really seems to have degraded as it has become increasingly bloated. I grit my teeth every time I hear platform ops say "hey, that deployment ticket last week... we noticed you didn't fill out the x, and z fields and also didn't create a follow-up ticket for future deployment to prod with the correct link to the implementation ticket"
// NOTE in the meantime, we added asynchronous loaders everywhere using
// a third party library which makes the page even slower to load, and
// increased the recommended CPU and RAM requirements for both the server
// and the client.
// We also added a noscript tag to tell the users they can't load the page
// without JavaScript so the loaders can load.
> 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.
In my mind, every todo in code is of this type - worth fixing (someday, maybe) but not worth tracking. If it needs to be tracked, put the details in the ticket and just link to the code, don't put a commment in there.
To me, the point of the todo comment is to see it if I am working/touching/utilizing that bit of code. That is the time it should be worked on, not when someone finally gets to a ticket in the ticket tracker.
It's all about the method of action - if the task is something that should be prioritized against other work, put it in a ticket. If it is a task that should only ever be done if I touch this bit of code, then put it in a TODO comment.
I think the key point is that if you put a TODO comment in the code, it should be resolved before merging. If it's important enough to leave in there, it should be an issue. I only use them as something to grep for and so that I don't lose my train of that as in "oh I need to fix that but I'm working on something else at the moment, write the TODO, finish what I'm working on, then go back to the TODO".
What if you're working on something, and you see some code that should be marked with TODO, entirely unrelated to your code? I think it's unrealistic to expect to be able to fix every issue you see.
Yes! I often add a CI check that TODOs are removed before merging a PR. Have them all you want in your branch, but do one of the above 3 things before merging (sometimes any `TODO`, sometimes `TODO_P0`).
I find CI integration also makes TODOs more helpful. You can use them to track a genuine TODO in a working branch, but CI will make sure you don't miss them.
When forced to point to a concrete issue by tooling, I often just end up rewording it - "Ideally this should X, but it Y". Comments are fine, lower overhead and don't require re-triaging later, and have all the context to immediately understand.
This rule is important because comments can get orphaned. Just leaving a comment is a recipe for a comment nobody knows why it’s there. Just make a ticket or do it now.
I don't understand this? The comment is next to the code it's mentioning. If the comment doesn't have enough context then the comment isn't long enough. Worst case you should be able to find necessary context in the blame.
I agree that for particularly complex issues you need to file a ticket, explain all the context, maybe give reasons on why it wasn't solved in the original commit. But for forced issues you can easily have the _opposite_ problem to what you're describing. That is: you're left with a bunch of skeleton issues filed only for the sake of shoving it into a TODO comment. Those tickets end up getting auto closed after X time anyways.
Obviously have guidelines, maybe even have a linter warning. But don't implement strict rules. It's a comment.
Very useful for flagging any O(n^2) that make assumptions about the size of N because N is not expected to exceed a certain size. Especially for when N inevitably exceeds that size.
Documenting it saves the poor dev doing profiling in the future a bit of effort so they can come up with the better solution that you failed to come up with when writing the code.
Often times code has to be written and committed and I don't have the time nor the brains to come up with a novel solution that solves a future performance issue that is not yet and is not expected to ever become a performance issue.
It's just saving the next person the trouble of thinking up and documenting the same approach you thought of while writing the code in the first place. As in, you know it doesn't matter now because the overall thing is plenty fast enough, but you can imagine a future where performance starts showing up as an issue and you wnat to leave a breadcrumb saying "this fruit here, it's a-hangin'".
I find it weird to use TODO for something you don't actually have to do. But you're apparently not the only one to do this, and as long as everyone who's working on the same code is on the same page it's fine I suppose.
I think in these same three categories but label them TODO, T0DO, and TOD0, respectively. I like that they look roughly the same when visually scanning through a file but are easy to grep for separately.
For me, XXX is a mental note to "fix this before your next pull request." If I'm being serious I'll set up CI to reject any code with a comment containing this string. So in that sense it would be the highest priority.
I like this style. In a project I worked on we had CI reject any FIXMEs outright and any TODOs that weren't accompanied by an issue ticket[^1], so the hierarchy would be
FIXME: I am leaving a note to myself to not get distracted, but this code is not considered finished/mergeable until it's resolved
XXX: this needs fixing soon, but the code will still be functional without it
TODO: this needs revisiting but the code is perfectly useable without it - a lower priority XXX
NOTE: this does something unusual and you need to bear in mind while working on this code
[^1]: the value of doing (or not doing) this is a subject that has already been extensively rehashed in sibling comments
NB(username,YYYY-MM-DD): Important documentation about XYZ thing that might break if you do something wrong. This is essentially a real comment, but calls for extra attention and care. [1]
TODO(username,[TICKET-ID,]YYYY-MM-DD): Something left not done, optionally with a (Jira) ticket.
If there are multiple authors or DRIs, replace `username` with `ldap_1+ldap_2+...`
I do something similar, I place an assertion instead of FIXME for code paths that are not yet finished and can be avoided. My TODOs are associated with possible tasks including a refactor for performance or clarity. My NOTEs are for tracking historical information and to capture thinking at the time that would not be immediately obvious from looking at the code.
Great in theory but these conventions are meaningless without tooling IMO. Assuming you are working in a team. Which is not to say they are meaningless - maybe there is or should be tooling for this.
But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999):
> Some hackers liken ‘XXX’ to the notional heavy-porn movie rating.
This seems plausible given the older culture ("this is metaphorically dirty, and therefore like porn", insert puerile snickering) and I can recall old jokes about "searching for" these markings. But I think it's also just about it visually standing out - the X character filling the terminal display cell with sharp lines.
I have often thought about doing exactly this, but one thing that always made me hesitate was the fact that nobody else seems to be doing it. Now that I finally see that others are actually using other labels than TODO I may actually start doing this, too.
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.
I'm sure in larger codebases it can get unwieldy with tons of TODOs from a lot of different people, but for personal projects I've always found them a good compromise.
For me it's saying "yeah I know it could be better but I'm not going to break my train of thought over this and context switch. It's not so critical as to break functionality, this would just be nicer."
I really do appreciate TODO hilighting in editors for the odd occasion where I get back to something on a whim and feel like doing a quick fix then. (It's probably not realistically that common though and most will sit there indefinitely)
I think the main thing is sometimes you want the signal that there is work to be done in the code. In that case even if you track it on JIRA, GH issues etc. you'd still want to link it. And a reference is a bet on continuity so without a description in the comment as well you might lose the meaning someday.
Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage? Many don't commit often enough and instead tangle together unrelated changes. The cherry on top is when the commit message is just "updating somefile.py" or something similarly unhelpful.
How would that be discovered? If I inline a TODO comment calling out some tech-debt that I (we, our team) had to take on, then in the future when the next person touches that logic they will see that comment and might address it. If it's in a commit message it might as well be invisible.
Discovered by the rest of your org? I don't see how a TODO in the code is more visible than a git commit message. In fact, at least it's possible that non-devs may still be able to see the git commit messages in a feed or have read access to repos.
`git blame` is to answer the question "who did this, when and why?", where the who and when are automatic and the "why" is a responsibility of the committer (and reviewers).
Instead of relying on people actively checking the git-blame for all of the code they're reading, why not just put a clearly obvious comment within the code itself?
What I take issue with is low quality writing. TODOs are a low quality comment. Commit messages that only tell "what" and not "why" are also low quality. Generally just not having a clean history to look at is bad project management.
Yes, that's fine. Developers can also put TODOs in their git commit message.
> Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage?
I have a tool which fails if it finds a TODO in a comment without a Jira link on the same line. Since it fails if it finds such things, it's great for CI/CD piplines to block PRs until all of the oddball ends have been tied up and made visible to the product team.
Alas, if we could get the product team to prioritize those TODOs then they can start to be removed from the codebase...
I'd rather see a TODO in the source file than in the commit message because of discoverability issues with commit messages.
Maybe that can be fixed? If I need to git blame the right line, and while ignoring miscellaneous commits like formatting changes, renames, and additional comment additions, then I'm probably not going to find the commit message. Also, if you do all of that just to find a vague commit message, then why bother digging next time?
Best tech-debt tracking I've seen is in the form of TODOs with mandatory links to the issue tracker (thanks to a silly regex pre-commit/pre-submit check) coupled with a team culture of adding such TODOs, as just adding the regex check will just cause lazy and sloppy engineers to not add a TODO at all, especially when facing pressure from other teams.
No, I knew there's some trickery to avoid part of the noise in git, but it's not enough as I won't be looking at that log or blame everytime I read a file. Using a TODO comment still seems better to me.
A TODO surfaces details where it wouldn't even occur to me that there's something interesting hidden in the log. Trying to find them feels like smashing the action button everywhere to get a random secret in a game, like secret doors in rtcw or finding stuff with the shovel in zelda.
Do you not use an IDE? It's fairly trivial to run macros or add something to the command palette. Maybe some personal scripts you have been honing over the years?
Usually strong opinions like this come with a more developed workflow.
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.
I still have to come across one of those issues. It may not be a priority, but it is a broken window (Pragmatic Programmer book). If it’s a won’t fix type of issue, just add it to the software docs.
> // 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).
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.
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
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.
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.
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.
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 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.
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.
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.
//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.
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 they would be lost. Comments are for understanding how something works. TODOs are for understanding how something might not work.
Edit: And if you put them in a tracker, they'd be distracting and confusing for team members less intimately familiar with the codebase, e.g. a PO. You could also choose a word other than "TODO", as long as it won't produce a ton of false positives in a search.
If you put them in a tracker, soon enough there will be somebody asking why 90% of the issues are not being worked on, will complain if they just disappear one day, and will disappear for political reasons.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
> 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.
There's no back-link mechanism for a ticket. If there were (when viewing the code there's some visual queue that there's a todo ticket open for this line) then I'd agree. Also consider the infuriating practice where managers (often with the help of supercilious bots) close tickets "just because".
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."
Sometimes "TODO" means something you would do if you had infinite time, refactor the code completely or something that will likely need to be revisited in the future but currently adds no value to implement.
I only use "TODO" eventually followed by a sub-classification like "TODO bug": it maximizes discoverability by other devs and tools, and allows for a lot of variants (both technical and/or functional) while still permitting a complete scan with a single grep.
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.
This is unrealistic, or possibly you just haven't used platforms/languages that benefit from a layer of record-keeping lower than is appropriate for a ticket-tracking system.
Also, a TODO doesn't mean you have not guarded against an edge case. A TODO could be anything that increases the health of the codebase or application. You can guard against an edge case, and then write a TODO on that guard that mentions that you'd like to recover from the edge case, rather than simply guard it.
While I don't necessarily agree with GP, this isn't a refutation. Yes, eliminating code smells entirely is, in typical development environments for sufficiently large projects, entirely unrealistic. That doesn't make them not smells.
Sometimes, it's "there is something wrong here but I cannot figure out a way to make it better yet without working nights and weekends for the next three months with no benefit to myself."
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.
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"
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
I'll say
// Hmm: This seems brittle. We might want to X, Y, Z this such that W.
My IDE will list all the TODOs and I don't like to clutter that list with stuff that isn't strictly necessary, but it is nice to have some string--"Hmm:", in this case--that I can grep for or recognize as indicating that I thought about this already.
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.
Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished. Issues in an external systems may also be overlooked by developers working on this particular code.
There are plenty of small things that are worth fixing, but not worth as much as the overhead of tracking them.
TODO in code is easy to spot when someone is working on this code, and easy to delete when the code is refactored.
I think the key distinction is that tracking in an external system exposes the task for triage/management/prioritization to people who aren't reading the code, while a TODO comment often leaves the message in exactly the spot where a programmer would read it if the possibility of a problem became an actual problem that they had to debug.
In my experience, these can often be replaced with logger.Error("the todo") or throw new Exception("the todo"), which read about as well as //TODO: the todo, but also can bubble up to people not actually reading the code. Sometimes, though, there's no simple test to trigger that line of code, and it just needs to be a comment.
> Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished.
Which is already what you're doing in that system, and what the system is designed for.
Source code is not designed to track and management issues and make sure they get prioritized, so you shouldn't be using your source code to do this.
We add TODOs during development, and then during review we either add a ticket and remove the TODO, or fix the issue as part of the PR and remove the TODO.
> Source code is not designed to track and management issues and make sure they get prioritized, so you shouldn't be using your source code to do this.
Indeed. Who in their right mind would think it is reasonable to track relevant tasks purposely outside of a system designed and used explicitly to get tasks done?
Also, no one prevents a developer from closing a ticket before triaging it. If you fix a TODO, just post a comment and close it. I mean, will your manager complain about effortlessly clearing the backlog? Come on.
This gives me an idea for a source control/task task tracking system where TODOs in code get automatically turned into tickets in your tracker, and then removed from your code automatically.
That way you don't fill your code with a list of TODOs and you'll still be able to track what you want to improve in your codebase.
It might not be the right tool for everyone, but I'd love it.
Check out Puzzle Driven Development.
You can leave the TODO in the comments- e.g. ruff the linter has an optional rule to disallow TODO comments unless it's followed by an issue url.
If you put that in the CI, then you can use TODOs either as blockers you wish to fix before merging, or as long term comments to be fixed in a future ticket.
Some years ago, I started to use FIXME to indicate that something is blocking the PR and needs to be done before merging, and TODO if something can be done at a later point in time. Then, CI only needs to grep for FIXME to block merging the PR, which works for practically any language. Works pretty well for me, maybe that tip can help others as well.
> Tracking in external system adds overhead not only for filing the issue, but also for triaging it, backlog management, re-triaging to see if it's still a problem, and then closing it when it's finished.
Filing the issue can take as long as writing the TODO message.
Triaging it, backlog management, re-triaging to see if it's still a problem... It's called working on the issue. I mean, do you plan on working on a TODO without knowing if it is still a problem? Come on.
> Issues in an external systems may also be overlooked by developers working on this particular code.
I stumbled upon TODO entries that were over a decade old. TODOs in the code are designed to be overlooked.
The external system was adopted and was purposely designed to help developers track issues, including bugs.
You are also somehow assuming that there is no overhead in committing TODO messages. I mean, you need to post and review a PR to update a TODO message? How nuts is that.
> There are plenty of small things that are worth fixing, but not worth as much as the overhead of tracking them.
If those small things are worth fixing, they are worth filing a ticket.
If something you perceive as an issue is not worth the trouble of tracking, it's also not worth creating a comment to track it.
Todos can also serve as a direction where you want the code to go to. Leaving this in the code ensures everyone working on it sees it, and every change they make can take this direction in mind.
Maybe THIS change finally warrants implementing foo, or at least refrain from implementing bar.
That's just form 3.
I think the author is basically arguing for #3 but not addressing the difference between a `TODO` comment vs. a non-`TODO` comment.
I guess the `TODO` terms has a certain visual flair that makes us immediately understand the class of comment. I guess that would be my best argument for keeping it a `TODO` comment instead of a regular one. But when you see the author arguing that `TODO` comments dont mean you need TO DO anything, it's kind of a smell, isn't it?
I find myself generally agreeing with the article's sentinment but think your option #3 of just making it a non-TODO comment an improvement.
Am I hallucinating or did IntelliJ have a TODO tracker? Webstorm doesn’t bug me about todos, but something I used to use did.
Rider definitely has a popup with a list of TODOs before you push to the remote. I assumed that originally existed in intellij... but never verified that.
Yes, it's in base IntelliJ. TODO and FIX tracking, IIRC.
It still does. But it’s a user option to run the scan when commiting (or pushing). So it may be disabled in your config.
>take 20 seconds to write it down and track it
You've described a TODO.
If I were to elevate it into a ticket system, besides obviously taking longer than 20 seconds, it would be a distraction, not a help.
I was just having this conversation with myself for another reason this morning (trying to define why automating processes is a force multiplier and mistake reducer). Because there’s little to no IDE integration for ticket tracking, swapping to the ticket system is a context switch. And the ticket system has ways of demanding your attention once you’re in there. If it succeeds now you’re pre-empted.
The thing about concurrency is that as long as you don’t know about a priority message you can continue to make progress on the task at hand. The moment you are aware of it you have to deal with it or have to explain yourself later. “I didn’t see it” goes a lot farther than, “I did but I was busy.”
My ex would try to check her work email on a Friday evening as we were on our way out the door for a trip out of town. A trip her boss likely knew about. That’s not why she’s my ex but it certainly didn’t help. That email arrived after you already left, lady. That’s your story and we are sticking to it. Don’t go looking for conflict, particularly when doing so affects people other than yourself.
I personally have no problem with the forcing function of a policy that makes you add a todo to a ticketing system.
It sets a bar for the todo to be at least more complex than creating a ticket. Any less and you can just do what the todo says to do.
Make the bar high enough and people won’t bother to do either and instead just hope for the best or keep their own list of TODOs elsewhere.
The point of a cheap informal method is to as low of a bar as possible so that more information is collected. As for always immediately fixing that’s the same as making everything the top priority, the true priority is lost.
Too many TODO comments and not enough tracked issues, that’s a sign that issue tracking has too much ceremony. Ban the use of TODOs and you lose even that information.
Perhaps a codebase could be watched such that new tracking issues are added and tracked implicitly when checked in by searching for new TODOs in the code. Similarly the tracking issue could be closed when the corresponding TODO is deleted from the code.
[dead]
I wish tracking took 20 seconds. In my org (big tech) a JIRA ticket has 10+ required fields.
Jira is awful because it has no opinions and leaves those decisions up to people who have terrible ones.
Jira really seems to have degraded as it has become increasingly bloated. I grit my teeth every time I hear platform ops say "hey, that deployment ticket last week... we noticed you didn't fill out the x, and z fields and also didn't create a follow-up ticket for future deployment to prod with the correct link to the implementation ticket"
That’s nothing to do with jira and everything to do with your platform ops team.
That’s only true if you think the person who made the torture device is not culpable for their customers using it as a torture device.
I don’t happen to believe that is true. Pandering to customers makes you part of the problem.
It feels like it takes 20 seconds just for the Jira page to load.
// TODO refactor to make page load faster
> 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.
In my mind, every todo in code is of this type - worth fixing (someday, maybe) but not worth tracking. If it needs to be tracked, put the details in the ticket and just link to the code, don't put a commment in there.
To me, the point of the todo comment is to see it if I am working/touching/utilizing that bit of code. That is the time it should be worked on, not when someone finally gets to a ticket in the ticket tracker.
It's all about the method of action - if the task is something that should be prioritized against other work, put it in a ticket. If it is a task that should only ever be done if I touch this bit of code, then put it in a TODO comment.
I think the key point is that if you put a TODO comment in the code, it should be resolved before merging. If it's important enough to leave in there, it should be an issue. I only use them as something to grep for and so that I don't lose my train of that as in "oh I need to fix that but I'm working on something else at the moment, write the TODO, finish what I'm working on, then go back to the TODO".
What if you're working on something, and you see some code that should be marked with TODO, entirely unrelated to your code? I think it's unrealistic to expect to be able to fix every issue you see.
Then I create a ticket and we refine it to see if it indeed needs to be addressed
This is how I use TODO as well. If it shows up in a pull request, it should be a red flag that the work isn't done.
If the todo is code you’re working on, yes.
If it’s a WTF about code that is next to the code you worked on, no. Boost the WTF ratio of code that deserves it.
Yes! I often add a CI check that TODOs are removed before merging a PR. Have them all you want in your branch, but do one of the above 3 things before merging (sometimes any `TODO`, sometimes `TODO_P0`).
I find CI integration also makes TODOs more helpful. You can use them to track a genuine TODO in a working branch, but CI will make sure you don't miss them.
When forced to point to a concrete issue by tooling, I often just end up rewording it - "Ideally this should X, but it Y". Comments are fine, lower overhead and don't require re-triaging later, and have all the context to immediately understand.
I have a single rule: Every todo needs the ticket number included.
// TODO: improve the routing https://jira.com/whatever/TIX-1234
This rule is important because comments can get orphaned. Just leaving a comment is a recipe for a comment nobody knows why it’s there. Just make a ticket or do it now.
I don't understand this? The comment is next to the code it's mentioning. If the comment doesn't have enough context then the comment isn't long enough. Worst case you should be able to find necessary context in the blame.
I agree that for particularly complex issues you need to file a ticket, explain all the context, maybe give reasons on why it wasn't solved in the original commit. But for forced issues you can easily have the _opposite_ problem to what you're describing. That is: you're left with a bunch of skeleton issues filed only for the sake of shoving it into a TODO comment. Those tickets end up getting auto closed after X time anyways.
Obviously have guidelines, maybe even have a linter warning. But don't implement strict rules. It's a comment.
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.
I'm using:
- TODO: will be needed before release, mandatory or else turn into another category. Blocks release.
- FUTURE: will be turned in to a TODO eventually, optional, often architectural
- MAYDO: nice to have, very optional
- PERF: do this if more performance is needed
+
some semantic tags related to domain
Opinion: TODOs are NOT code smells, they accrue around the most valuable parts of the codebase.
I like these, although I wonder about the value of speculating about a performance optimization while neither just doing it nor profiling.
Very useful for flagging any O(n^2) that make assumptions about the size of N because N is not expected to exceed a certain size. Especially for when N inevitably exceeds that size.
Documenting it saves the poor dev doing profiling in the future a bit of effort so they can come up with the better solution that you failed to come up with when writing the code.
Often times code has to be written and committed and I don't have the time nor the brains to come up with a novel solution that solves a future performance issue that is not yet and is not expected to ever become a performance issue.
It's just saving the next person the trouble of thinking up and documenting the same approach you thought of while writing the code in the first place. As in, you know it doesn't matter now because the overall thing is plenty fast enough, but you can imagine a future where performance starts showing up as an issue and you wnat to leave a breadcrumb saying "this fruit here, it's a-hangin'".
Personally I use
FIXME: something broken that needs fixing
TODO: potential features/improvements
WARN: noting complex edge cases/weird behaviors
I find it weird to use TODO for something you don't actually have to do. But you're apparently not the only one to do this, and as long as everyone who's working on the same code is on the same page it's fine I suppose.
I think in these same three categories but label them TODO, T0DO, and TOD0, respectively. I like that they look roughly the same when visually scanning through a file but are easy to grep for separately.
For me, XXX is a mental note to "fix this before your next pull request." If I'm being serious I'll set up CI to reject any code with a comment containing this string. So in that sense it would be the highest priority.
I like this style. In a project I worked on we had CI reject any FIXMEs outright and any TODOs that weren't accompanied by an issue ticket[^1], so the hierarchy would be
FIXME: I am leaving a note to myself to not get distracted, but this code is not considered finished/mergeable until it's resolved
XXX: this needs fixing soon, but the code will still be functional without it
TODO: this needs revisiting but the code is perfectly useable without it - a lower priority XXX
NOTE: this does something unusual and you need to bear in mind while working on this code
[^1]: the value of doing (or not doing) this is a subject that has already been extensively rehashed in sibling comments
NB(username,YYYY-MM-DD): Important documentation about XYZ thing that might break if you do something wrong. This is essentially a real comment, but calls for extra attention and care. [1]
TODO(username,[TICKET-ID,]YYYY-MM-DD): Something left not done, optionally with a (Jira) ticket.
If there are multiple authors or DRIs, replace `username` with `ldap_1+ldap_2+...`
[1] https://en.wikipedia.org/wiki/Nota_bene
Absolutely. The ability to search for these flags before a commit, during a review or release is so valuable.
I do something similar, I place an assertion instead of FIXME for code paths that are not yet finished and can be avoided. My TODOs are associated with possible tasks including a refactor for performance or clarity. My NOTEs are for tracking historical information and to capture thinking at the time that would not be immediately obvious from looking at the code.
Great in theory but these conventions are meaningless without tooling IMO. Assuming you are working in a team. Which is not to say they are meaningless - maybe there is or should be tooling for this.
This is pretty much what I do too. `XXX` is "Look here! This is important!" or "You might not expect this!"
I rarely use NOTE, but I have on occasion.
What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.
It has some ancient history as a morse code distress signal: https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03...
And it shows up in some old BSD code: https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/
But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999):
https://www.oracle.com/java/technologies/javase/codeconventi...
Unclear, but we do have https://www.catb.org/jargon/html/X/XXX.html
> Some hackers liken ‘XXX’ to the notional heavy-porn movie rating.
This seems plausible given the older culture ("this is metaphorically dirty, and therefore like porn", insert puerile snickering) and I can recall old jokes about "searching for" these markings. But I think it's also just about it visually standing out - the X character filling the terminal display cell with sharp lines.
Hm, this made me wonder about the use of XXX as a label for alcohol bottles in cartoons.
It turns out it refers to "moonshine that has been distilled 3 times, reaching very high alcohol content".
Amsterdam.
I have often thought about doing exactly this, but one thing that always made me hesitate was the fact that nobody else seems to be doing it. Now that I finally see that others are actually using other labels than TODO I may actually start doing this, too.
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.
I'm sure in larger codebases it can get unwieldy with tons of TODOs from a lot of different people, but for personal projects I've always found them a good compromise.
For me it's saying "yeah I know it could be better but I'm not going to break my train of thought over this and context switch. It's not so critical as to break functionality, this would just be nicer."
I really do appreciate TODO hilighting in editors for the odd occasion where I get back to something on a whim and feel like doing a quick fix then. (It's probably not realistically that common though and most will sit there indefinitely)
I really appreciate the feature of Jetbrains IDEs whereby the codebase is indexed for TODO comments.
I often find myself with some time on a plane and cracking open my laptop to dig through to the TODOs that are shown is really cathartic.
I think the main thing is sometimes you want the signal that there is work to be done in the code. In that case even if you track it on JIRA, GH issues etc. you'd still want to link it. And a reference is a bet on continuity so without a description in the comment as well you might lose the meaning someday.
There are readily available MCP servers for JIRA that let the AI fill out the tickets for you, right from inside Cursor.
Put it in your git commit message.
Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage? Many don't commit often enough and instead tangle together unrelated changes. The cherry on top is when the commit message is just "updating somefile.py" or something similarly unhelpful.
How would that be discovered? If I inline a TODO comment calling out some tech-debt that I (we, our team) had to take on, then in the future when the next person touches that logic they will see that comment and might address it. If it's in a commit message it might as well be invisible.
Discovered by other devs? git blame.
Discovered by the rest of your org? I don't see how a TODO in the code is more visible than a git commit message. In fact, at least it's possible that non-devs may still be able to see the git commit messages in a feed or have read access to repos.
`git blame` is to answer the question "who did this, when and why?", where the who and when are automatic and the "why" is a responsibility of the committer (and reviewers).
A TODO is about something that is not there yet.
Instead of relying on people actively checking the git-blame for all of the code they're reading, why not just put a clearly obvious comment within the code itself?
I'm actually saying people can do both.
What I take issue with is low quality writing. TODOs are a low quality comment. Commit messages that only tell "what" and not "why" are also low quality. Generally just not having a clean history to look at is bad project management.
> Put it in your git commit message.
Yes, that's fine. Developers can also put TODOs in their git commit message.
> Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage?
I have a tool which fails if it finds a TODO in a comment without a Jira link on the same line. Since it fails if it finds such things, it's great for CI/CD piplines to block PRs until all of the oddball ends have been tied up and made visible to the product team.
Alas, if we could get the product team to prioritize those TODOs then they can start to be removed from the codebase...
I'd rather see a TODO in the source file than in the commit message because of discoverability issues with commit messages.
Maybe that can be fixed? If I need to git blame the right line, and while ignoring miscellaneous commits like formatting changes, renames, and additional comment additions, then I'm probably not going to find the commit message. Also, if you do all of that just to find a vague commit message, then why bother digging next time?
Best tech-debt tracking I've seen is in the form of TODOs with mandatory links to the issue tracker (thanks to a silly regex pre-commit/pre-submit check) coupled with a team culture of adding such TODOs, as just adding the regex check will just cause lazy and sloppy engineers to not add a TODO at all, especially when facing pressure from other teams.
Maybe this is what you're thinking of?
git log -pM --follow --stat -- path/to/your/file
This will get you all the changes a file has gone through. You can also add --ignore-all-space if that's a problem.
No, I knew there's some trickery to avoid part of the noise in git, but it's not enough as I won't be looking at that log or blame everytime I read a file. Using a TODO comment still seems better to me.
A TODO surfaces details where it wouldn't even occur to me that there's something interesting hidden in the log. Trying to find them feels like smashing the action button everywhere to get a random secret in a game, like secret doors in rtcw or finding stuff with the shovel in zelda.
Do you not use an IDE? It's fairly trivial to run macros or add something to the command palette. Maybe some personal scripts you have been honing over the years?
Usually strong opinions like this come with a more developed workflow.
Most commit messages are bad, but commit messages are a terrible TODO list.
You're right they are a terrible TODO list, but old comments in the code are worse because you don't have as much context to work with.
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).
I was on a team that used `// TBD: [...]` for this purpose, so that the "TODO people" wouldn't notice.
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.
I still have to come across one of those issues. It may not be a priority, but it is a broken window (Pragmatic Programmer book). If it’s a won’t fix type of issue, just add it to the software docs.
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).
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.
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
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.
Surely it's the data that needed to be encrypted?
No, the comment.
The example seems like more of a FIXME than a TODO.
It’s a clear error, but likely unimportant enough to bother addressing.
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.
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.
"Ideally, this code would X. It's acceptable that it doesn't, but if you do change it, considering doing this differently."
then it's not a TODO, it's just part of the comments. Promoting semantic diffusion IMHO is not a good practice in software development.
How would you quickly identify something as "would be better if."
It's a "to do" but on a long (perhaps indefinite) timeframe.
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.
Yeah, TODOs should start with a verb which tells you to, you know, DO something.
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 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.
"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.
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.
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:
and 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.
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.
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.
That example from article should be regular comment not a TODO comment.
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.
That's what FIXME is for
Agreed, though by the same token, unactionable `TODO`s should probably be `HACK`s or `NB`s.
But also...
> 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.
The most frustrating thing to find is a TODO for a half baked thought about some inconsequential logic. Delete!
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?
Then they would be lost. Comments are for understanding how something works. TODOs are for understanding how something might not work.
Edit: And if you put them in a tracker, they'd be distracting and confusing for team members less intimately familiar with the codebase, e.g. a PO. You could also choose a word other than "TODO", as long as it won't produce a ton of false positives in a search.
> Comments are for understanding how something works
Even better: for understanding why some code does this surprising or seemingly complicated thing it's doing
If you put them in a tracker, soon enough there will be somebody asking why 90% of the issues are not being worked on, will complain if they just disappear one day, and will disappear for political reasons.
What does it mean to be lost? Why would a TODO comment not be lost, versus a comment without that prefix?
For that reason I’ll often prefer the word REVISIT instead of TODO. Kinda less obligatory.
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!
Hi!
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.
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.
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.
Replace the not-TODOs with NOTEs.
For example, this TODO:
…is a NOTE, albeit a gratuitous one.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.
To me, "NOTE" still implies that the comment is about describing the existing state, rather than a desired future state.
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]
What does NB stand for?
Edit: "Nota bene" apparently: https://en.wikipedia.org/wiki/Nota_bene
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.
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.
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.
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.
> 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.
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.
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.
There's no back-link mechanism for a ticket. If there were (when viewing the code there's some visual queue that there's a todo ticket open for this line) then I'd agree. Also consider the infuriating practice where managers (often with the help of supercilious bots) close tickets "just because".
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`.
Sometimes "TODO" means something you would do if you had infinite time, refactor the code completely or something that will likely need to be revisited in the future but currently adds no value to implement.
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.
I only use "TODO" eventually followed by a sub-classification like "TODO bug": it maximizes discoverability by other devs and tools, and allows for a lot of variants (both technical and/or functional) while still permitting a complete scan with a single grep.
I think common terminology for there are FIXME, TODO, XXX in that order, but YMMV
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.
This is unrealistic, or possibly you just haven't used platforms/languages that benefit from a layer of record-keeping lower than is appropriate for a ticket-tracking system.
Also, a TODO doesn't mean you have not guarded against an edge case. A TODO could be anything that increases the health of the codebase or application. You can guard against an edge case, and then write a TODO on that guard that mentions that you'd like to recover from the edge case, rather than simply guard it.
>This is unrealistic
While I don't necessarily agree with GP, this isn't a refutation. Yes, eliminating code smells entirely is, in typical development environments for sufficiently large projects, entirely unrealistic. That doesn't make them not smells.
Sometimes, it's "there is something wrong here but I cannot figure out a way to make it better yet without working nights and weekends for the next three months with no benefit to myself."
TODO: Remove the 'FillInData' function call after bug/<id> is fixed.
There is always an unhandled edge case
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?
...No?Ok fine, how do you track completed TODOs?
Ok fine, I'll show myself out.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
I'll say My IDE will list all the TODOs and I don't like to clutter that list with stuff that isn't strictly necessary, but it is nice to have some string--"Hmm:", in this case--that I can grep for or recognize as indicating that I thought about this already.WTF is "TODO?"
Step one is: learn English.
great post