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.
I've also seen good use of automation tools that monitor the codebase for TODOs and if they last for more than a couple weeks escalate them into a "real" ticketing system.
(I've also seen that backfire and used to punish engineering.)
SonarQube, for instance, will flag TODOs as "Code Smells" and then has some automation capabilities to eventually escalate those to tickets in certain systems if plugins are configured.
I've also seen people do simpler things with GitHub Actions to auto-create GitHub Issues.
> I've also seen good use of automation tools that monitor the codebase for TODOs and if they last for more than a couple weeks escalate them into a "real" ticketing system
Im sorry but that’s exactly the kind of automation that sounds helpful in theory but ends up creating bloat and inefficiency in practice. Like the article says, the second a TODO gets a timer/deadline attached, it stops being a quick, lightweight note and turns into process overhead (note the distinction between something that is urgent and needs fixing now, and something that really is just a TODO).
Maybe a weird way to put it, but it’s like a TODO that used to be lean and trail-ready - able to carry itself for miles over tough terrain with just some snacks and water - suddenly steps on a scale and gets labeled “overweight" and "bloated" and flagged as a problem, and sent into the healthcare system. It loses its agility and becomes a burden.
"But the TODO is a serious problem that does need to get addressed now" Ok then it was never actually a TODO, and thats something to take up with the dev who wrote it. But most TODOs are actually just TODOs - not broken code, but helpful crumbs left by diligent, benevolent devs. And if you start to attack/accuse every TODO as "undone work that needed to be done yesterday" then youll just create a culture where devs are afraid to write them, which is really stupid and will just create even more inefficiency/pitfalls down the road - way more than if you had just accepted TODOs as natural occurrences in codebases
> 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.
> Which is already what you're doing in that system, and what the system is designed for.
No it isn't. The system is designed to get managers to pay for it and it does that very well, it's very ineffective at tracking or triaging issues.
> 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.
Most things that people build systems for managing outside of the source code repo end up being less effective to manage that way.
This is just intellectually lazy IMO. "Ticket management software isn't good at managing tickets, it's just good at getting stupid CTOs to pay for it because execs are stupid didn't you guys know?"
I'm sure that's true for enterprise bloatware, but there are dozens of excellent open source and/or low cost issue trackers. Hell, Trello will do about 90% of what you need out of the box if you're operating with 1-3 people.
> This is just intellectually lazy IMO. "Ticket management software isn't good at managing tickets, it's just good at getting stupid CTOs to pay for it because execs are stupid didn't you guys know?"
Far more intellectually lazy to assume that because people pay for it it does something useful. Have you actually tried working without a ticketing system, not just throwing up your hands as soon as anything went wrong but making a serious attempt?
The main problem I have with ticketing (and project management) systems is that I can't get the people asking me to do things to use the system. I'll set it up and show them how to use it, and then they tell me about issues via email or text message or voice call. I end up entering the tickets/tasks myself, at which point I might as well be using my own org-mode setup.
From all I've seen, heard, and read about that problem over the decades (yup, I think it's not mere years any more):
The only solution is to be rock-solid in refusing to do anything if there isn't a ticket for it. Your nine-thousand-percent-consistent reply to those emails, text messages, and voice calls needs to be "Yeah, make a ticket about it. I've shown you how, and that's the way we do it. No ticket, no action from me."
If you can't be that "mean" about it, you'll have to be a make-my-own-tickets doormat forever. In that perspective, doesn't feel all that "mean" any more, does it?
Where I'm at, we have a bot that automatically creates a ticket for IT any time someone posts a message to the #it-help channel on Slack. It even automatically routes the ticket based on the content of the message with decent accuracy.
Perhaps I've been spoiled having worked almost exclusively in organizations where it's completely acceptable to get a message on Slack, or Teams, or email, or whatever, with some bug or issue, and respond with "please create a ticket" and the person... creates a ticket.
Yeah if nobody uses the system, or if you have to expend organizational capital to get them to do it (they view it as doing something for you instead of just doing their job), the system will by definitely be worth less and be less helpful.
Has anyone ever made a language or extended a language with serious issue tracking? I can definitely imagine a system where every folder and file can have a paired ticket file where past, future and current tasks are tracked. Theoretically, it could even bind to a source management extension for the past ones. It won't ever be as powerful and manager-friendly as JIRA, but it would be good enough for many projects.
There are various things built on git (the issues don't need representation in the current state of the source necessarily after all) but I'm not aware of any with any traction - it's a hobby Show HN thing, it appeals to us, but not to product.
I think it'd be cooler to have it as part of the source and kind of build incrementally. So you'd have the bits in code that get added to the pair file that will then be added to the directory file... Then you can add other pairs for things like test results, and it could be decent. Some Lego Logseqesue thing :)
I wouldn't use git as a basis for it since then management is completely out. Hell, I'm probably out as well since I see git as a necessary evil.
> 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.
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.
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.
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.
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.
Notably, if that TODO is turned into a ticket, there's a good chance it'll get triaged and eventually marked as cancelled/wontfix. Which is a perfectly reasonable thing to do when part of backlog management is saying no to things that'll never get prioritised. But, that work is still sitting there not done, and capturing that _somewhere_ has value, and alongside the code is about as context-rich as you can hope for.
I have often problems with these 20 seconds tickets. I takes another 20 minutes to call the author and ask what he meant by writing these few meaningless words and what’s exactly is the issue. Then add useful description to the ticket and look who is the responsible developer for the part. So no, 20 second tickets are problems and time waste, not the solutions.
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"
Ah, sorry I think I communicated in an unclear way. Yeah, we have some annoying processes at my office but a big reason that this sort of request sucks for me is that Jira is bloated, slow, confusing and buggy in a way it wasn't 5-10 years ago.
My experience is that if you give a “better” tool to a bad team they’ll just do something outside the tool. I have never worked with a team who has had a roadmap in jira - there’s always a corresponding excel sheet for that. The best defence against this practice is strong leadership and buy in to the value of the tool.
Personally I run myself on a bullet ish journal and I’d probably run my team on Trello given the choice.
> ...and I’d probably run my team on Trello given the choice.
For how much longer, though? Been quite a while since Trello was bought by Atlassian; dunno how badly Jira-fied it is by now, but I can only imagine it's going to get more and more so.
// 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.
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.
> That is: you're left with a bunch of skeleton issues filed only for the sake of shoving it into a TODO comment
Nobody says it needs to be one ticket per TODO. For example, I usually maintain a CSS punch list ticket to avoid too much yakshaving when developing functionality. Not only will it be more likely to get scoped and done, but another dev will know exactly where the fixes are needed by grepping for the ticket number.
But the other upside is that if it's really not worth filing a ticket for, why not just do it? I'm curious what scope of work you think is worth tracking in TODOs but not tickets. If it would be a point of work it probably deserves a ticket. If it's less than a point of work, shouldn't you just do it?
> Those tickets end up getting auto closed after X time anyways.
That feels like it reinforces my argument to me. If you can't make time for it when it's a ticket, how would you make time when it's just a comment? At least if the team decides in grooming that the work doesn't really need to be done, it's a group decision and not just me passing the buck.
> 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.
> 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.
Its easy to say that, and probably true, but in a large company with a shared codebase, you don't always have that kind of control. Someone intends to fix something, then the work gets deprioritized or they leave the company or forget.
Maybe you've never seen a comment and realized that the code that goes with it isn't there anymore, but I have. Comments and documentation are important but there's a spectrum of usefulness. On one end it "TODO: Fix this later" and on the other end are comments that are really important with a whole range in between.
The reality is, tickets are the way of making sure work gets scoped and accounted for. If your company measures velocity, having the actual amount of work you do represented in tickets is the way you show what you are actually doing all day. Why wouldn't you want future work to be ticketed? Who does it help?
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
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.