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.
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.
> 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.
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.
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.
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.
As Hinkley says, it's a task switch cost. Tickets may also involve a whole load more circus. They get seen by managers with metrics. The advantage of an in-place TODO is precisely that it doesn't get seen by people to whom it is not relevant, and that it can be left indefinitely.
In each practical project, there is an order of magnitude more things than you could do. One of the crucial job is to prioritize things well, knowing the context.
Regular tasks trackers put things outside of context. Low-priority things might go better in code. That is, you don't need to care about performance of a particular function as it does not matter. But when it starts to matter, and you see "TODO: cache results to speed up", you see an easy win.
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 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.
Any MBA in the comments- those issue growths will make me look bad in front of my superior- we should delete all those issues once a year.
Thus introducing the ToDODOs - which is a attempt to hold memory of important tasks facing extinction through cooperate dementia, which those who hold idealistic views of the stakeholders while engineering processes have no living memory of due to job hoping.
> 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.
Issue trackers are often politicized. You get projects where they auto-close stale issues. Or where they're resistant to creating issues that they know that realistically nobody is going to work on this in the foreseeable future.
TODOs are an excellent place for developers to describe where they'd like to go with a given pile of code if they had the time, and realistically that kind of work isn't suitable for every issue tracker depending on who has access to that issue tracker and who has opinions about what goes in there.
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.
> This rule is important because comments can get orphaned.
I've seen this argument in multiple discussion, especially against adding comments or documentation in code because they can become outdated.
But I really strugle to agree : comments/doc ARE part of the code. If you keep outdated comment or documentation in your code without anyone noticing, I'd say you have a pretty big issue with your review process.
4. Take a look at TODOs while maintaining the code, and promote them to the issue tracker if you feel like their time has come or have time to fix them. Take note that it's being actively worked on, on the codebase.
Eat your veggies. All veggies matter. Be flexible.
P.S.: This is what I do. My IDE gives a nice list of them.
It’s worth noting that 1. is not mutually exclusive with writing a TODO.
In fact, on my team, all TODOs must have a bug in parentheses immediately afterwards to satisfy the linter. So not only not mutually exclusive, but the opposite.
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.
Sometimes the value is just in capturing that thought in situ, even if it never gets acted on. It's less about task management, more about code archaeology
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.
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.
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.
The godoc[0] tool provides minimal support for doing something with these comments via its “-notes” flag. It renders any TODOs (or BUG or whatever can be specified by regexp) in the code docs web page. I personally wouldn’t go beyond a single type of note but just having them show up together in the code documentation may be handy depending on the workflow.
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.
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.
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...
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.
Well, if TODOs are not for doing, how about just not putting 'TODO' in front of them? Maybe we could sometimes attempt to use words to stand for what they actually mean. Could that possibly be helpful for peoples understanding?
Also, the first and most important place for putting TODO's is the issue tracking system so I think in most cases they do not have to be in the code. I might allow them occasionally if they refer an issue in the issue tracking system. Another use of TODO comments that is not necessarily bad is if you yourself or someone else is supposed to resolve all of them before the relevant code is merged into mainline.
> // 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.
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.
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).
Readit News
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.
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.
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.
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.
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.
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.
THANK YOU
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.
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.
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.
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.
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.
Deleted Comment
In each practical project, there is an order of magnitude more things than you could do. One of the crucial job is to prioritize things well, knowing the context.
Regular tasks trackers put things outside of context. Low-priority things might go better in code. That is, you don't need to care about performance of a particular function as it does not matter. But when it starts to matter, and you see "TODO: cache results to speed up", you see an easy win.
Maybe THIS change finally warrants implementing foo, or at least refrain from implementing bar.
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.
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.
Thus introducing the ToDODOs - which is a attempt to hold memory of important tasks facing extinction through cooperate dementia, which those who hold idealistic views of the stakeholders while engineering processes have no living memory of due to job hoping.
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.
TODOs are an excellent place for developers to describe where they'd like to go with a given pile of code if they had the time, and realistically that kind of work isn't suitable for every issue tracker depending on who has access to that issue tracker and who has opinions about what goes in there.
// 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 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've seen this argument in multiple discussion, especially against adding comments or documentation in code because they can become outdated.
But I really strugle to agree : comments/doc ARE part of the code. If you keep outdated comment or documentation in your code without anyone noticing, I'd say you have a pretty big issue with your review process.
Eat your veggies. All veggies matter. Be flexible.
P.S.: This is what I do. My IDE gives a nice list of them.
In fact, on my team, all TODOs must have a bug in parentheses immediately afterwards to satisfy the linter. So not only not mutually exclusive, but the opposite.
- 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.
- 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.
FIXME: something broken that needs fixing
TODO: potential features/improvements
WARN: noting complex edge cases/weird behaviors
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
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
[0]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc
I rarely use NOTE, but I have on occasion.
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.
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 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.
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.
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.
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...
Deleted Comment
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.
Also, the first and most important place for putting TODO's is the issue tracking system so I think in most cases they do not have to be in the code. I might allow them occasionally if they refer an issue in the issue tracking system. Another use of TODO comments that is not necessarily bad is if you yourself or someone else is supposed to resolve all of them before the relevant code is merged into mainline.
> // 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).
// 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.
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
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.
It’s a clear error, but likely unimportant enough to bother addressing.
You've already gone to the effort of determining the trigger and the reasons for the error, so you're probably 80% there.
It drives me insane that so many tools/processes treat TODOs as essentially code smells.
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).