This is why I set up linting rules to error when people push "TODO" comments.
Either just do it, or put a work item in the place where you actually track work (Jira or equivalent) so it has at least a chance of getting done. Otherwise you'll end up with the typical 5-to-10 year old TODO comment from a completely different era that helps nobody.
If you're going to leave a comment, leave context around why the hacky solution was chosen at the time of writing, and why you didn't do the "correct" alternative.
This is a good way to loose valuable knowledge. People will just commit without the TODO. In fact many won't even have thought of the TODO in the first place, because they were not aware of a potential pitfall. Be happy if you get a TODO, if you don't it will work but not as well.
I find TODOs useful even if the fix is never implemented as long as there’s a proper explanation for the TODO especially when I’m reading the code as it explains why something expected isn’t happening. It was simply not implemented as opposed to being a bug.
The codebase I worked on for 12 years (before I quit recently) had some TODOs in the codebase that were put there before I was hired. They didn't harm anyone and they were interesting to see the direction that the people who originally wrote the code thought it should go.
IMO, a commit without a TODO is very very close to a commit with an untracked TODO. If somebody decides that the issue isn't worth filing a ticket then okay. If somebody isn't willing to file a ticket then it isn't like they were likely to write a detailed comment explaining all of the relevant context. "TODO - clean this up" is pure noise.
A loose TODO lying around the codebase almost certainly won't actually get acted on and there is no opportunity to discuss or prioritize it.
It really isn't. If you have anything relevant to add regarding your hack, post it in the ticket. That's the first thing that will be read when someone picks it up. Otherwise you're just polluting the code with good intentions.
What happens when the company decides to migrate from JIRA to something else? It wouldn’t take any special effort to migrate the TODO but in my experience the old JIRA is going to be stale and abandoned entirely in a year. No one will even remember or think to look back at it, and new hires won’t even know it exists.
> What happens when the company decides to migrate from JIRA to something else?
Aren't you grasping at straws? How many times do you believe a project changes it's ticketing system? So far I saw that happening a grand total of zero times.
Meanwhile, I've repeatedly worked on legacy projects which have decades-old TODO/FIXIT items, which serve no purpose other than being noise and serving as topic in water-cooler shit chat.
I think we're on our 4th or 5th ticketing system over 15 years. (We're also on our 3rd revision control system, but the code and comments obviously migrated seamlessly across both of those transitions.)
Open Office changing ticketing systems three times. The first time I copied over a few dozen of my most important bugs, the second time I copied over the absolute most important bugs, and the last time I did nothing.
Nobody was reading, triaging, or fixing them anyway.
Ticketing systems tend to increase in price over time. I know one nameless company looking to migrate after their current system increased in price. Open source isn't any cheaper, you still have to pay admins.
Though one other reason to migrate is the forms are complex and full of required fields nobody understands. Migration will get you past that to what matters, but only for a few years before the groups that required those fields in the first place come back and demand it with the same good but forgotten reasoning as the first time. If this is you, get your act together.
>> This is a good way to loose valuable knowledge.
> It really isn't.
Tickets, internal emails etc are exactly the kind of things that tend to get lost when codebase is sold, sublicensed or open-sourced.
If the codebase contains underwater cliffs, then those remarks are best kept as close to code as possible so that every time someone works with a particular class or function, they have right before their eyes that "this function will slow to a crawl when you have more than 32 767 files concurrently open". It's very expensive to find out such limitations post-fact.
You may very well call such limitations "hacked-together code", but if there has so far never been the need to have more than 10 files concurrently open (but there is a slim chance that such need may arise one day), then implementing support for infinite number of concurrently open files is once again just a waste of resources.
I see no reason why ticket system should be cluttered with hypotheticals like this.
Okay. What percentage of codebases have this happen? How often does this happen unexpectedly in a way that you care? Is any purchaser going to say "oh - but all of your TODOs are in tickets rather than comments so I won't buy it"? Is there no way of reflecting the internal tickets to github issues or whatever you are using to track the open sourced version of your codebase?
Often when I write a TODO, it's because it's because I'm not going to remember to write it down anywhere else. I'm certainly not opening JIRA for it, so this is as good as it's going to get.
Every once in awhile we grep through the TODOs and see if we should write some tickets from them. Works fine.
That's the universe telling you the TODO is useless noise that points to a workitem that no one, not even you, find it relevant enough to track or work on.
When that happens, do everyone around you a favour and leave out the TODO comment.
Nothing is important enough to be worth using JIRA for. When a company or team adopts JIRA it's the universe telling you that they've given up on doing anything valuable or useful. Trying to make such a codebase better is an exercise in futility; writing TODOs is as good a way to pass the time and collect a paycheck as any other, and any vestigial useful work to be done is more likely to be tracked in TODOs than in JIRA tickets.
This is a great way of introducing a bug. The TODO is only visible to somebody looking at the code. If somebody changes a caller to send over bars but doesn't check the comment then you've got a bug. If instead this was linked to the feature request to add support for bars then you've got the relevant context right there on the ticket and whoever is implementing support for bars is much less likely to miss it.
I write TODO for something that would be too disruptive to do as part of the current change but nice to have done. E.g refactoring a bunch of files - one of them should be renamed but that would add every file that refers to it to the change and make it harder to see the real work done. Next time I’m in that code with a simple change, I can submit a rename CR that doesn’t have anything else mixed up in it.
> I write TODO for something that would be too disruptive to do as part of the current change but nice to have done.
One more reason to not have a TODO item and instead track work on a ticket. Sneaking fixes/changes as part of other tickets mixes up the rationale for tickets and makes changes harder to track. If all you're doing is a cleanup then all the more reason why it should be in an independent PR tracked accordingly.
Where it will never be picked up, because rework tickets never get prioritized over feature work until something breaks.
And when some future engineer comes along and asks themselves why the hell this code is the way it is, they'll have to git-blame, dig through commits, find PRs for commits, hopefully find referenced ticket numbers, read those, and play archeologist to try to reconstruct whether there's good reason for the existing code's being from those indirect signals. Whereas a simple "TODO" could just tell said future engineer what they ought to know.
I sincerely appreciate a well-written TODO, and I make every effort to write good TODOs for others.
There’s definitely lost linkage of knowledge if you can’t reference the ticket from your editor, which for many if not most workflows means you never can. The loss is that an unadorned hack may have a corresponding ticket, with no way of knowing there’s even anything to look for. The workflow challenge is chicken-egg: people seldom file a ticket on proposed, unmerged changes, and most teams would balk at the concept without specific procedures in place; people definitely don’t go back after a change is merged to annotate a hack with whatever ticket was filed for posterity.
IME, a better solution is keeping the TODOs (or FIXMEs or whatever your preferred label[s]), with linter rules to require aging them so they must be addressed eventually, somehow. Even if you address them by removing them. At least then there’s some possibility of relinking them later, tied directly to the commit history.
I agree with your point about polluting the code with good intentions, however. And I agree with the article author’s point that most of the time you’ll not go back and fix it. Those points combined suggest that most TODOs should actually just be explanatory comments. In fact, as someone who writes very few code comments, I think a good heuristic for when to write them is my usual “does someone need this explained?” (either by my anticipation or by their direct questioning) plus “would I be inclined to write a TODO about this?”
I agree with the OP - you have immediately lost the linkage between the lines of code and the problem description - maybe you put a reference to the lines / modeule in the ticket but really, why bother.
You could do "TODO fix the foobar because flange see Ticket 1234" (and I have a todoinator to automate that but I think a ticket should be more meaty than a todo but perhaps I am fooling myself
You’re absolutely fooling yourself - a ticket is a unit of work. Trying to hide tech debt by keeping it out of the project management system is not beneficial.
The code base is the project management system - the dialogue between developers is the way code is developed - and the project management system is a pale copy of the real system used to keep non-literate people happy and feel they have some input.
Progress is measured by working software not closed tickets.
No one's trying to hide anything. The target users of project management systems, product owners and anyone with with a project manager title, typically neither care about nor understand the value of rework. In their view, the dev teams should be creating maximum value at all times, which they understand as either adding features or putting out fires. Rework tickets do not get prioritized until they're identified as the cause of lost value.
The inevitable question is "well why wasn't it written correctly to begin with?" even if the reason, as is typical, was pressure from product managers in the first place.
> You could do "TODO fix the foobar because flange see Ticket 1234"
No, you should create Ticket 1235 - fix foobar, add additional info such as rationale and the definition of done, and add Ticket 1234 as related/blocks.
Xcellent point - and we need ways to sync the two but based in code. I am tempted to try and build something that uses module and line number and bags of the comment to build a unique reference for the ticket to point back to - but I wonder about code movement and have never done it
And that ticket will be forever ignored. On the other hand, if there’s a TODO in the code, someone might fix it the next time they’re editing that part of the code.
A team that spends all its time grooming the backlog is not spending time on reading code, logs inputs, output, data etc.
We have fooled ourselves into thinking ticketing systems represent living documents but they don't - a high functioning team can have "hey I will fix the foobar by adding a cromulent adjutant" in a office (!) call or even an email.
A low functioning team knows no one will get round to fixing it
Your team should be grooming and prioritizing the backlog. If the tech debt exists but the business doesn’t value working on it, then yes it won’t get worked. But it also wouldn’t ever get done as some stray //TODO either.
Unless you're in a Scrum team and "The Product Owner is responsible for the Product Backlog, including its content, availability, and ordering." is taken to mean that the PO has the final say on what's prioritized. If your PO has a project manager title, as most do, and they see their career advancement is tied to shipping features on or ahead of schedule, then indeed, that ticket will be forever ignored.
Then don't make it "stray" - parse the code for todos and other lintable items - and yes some grooming is needed - but don't make the ticketing system drive the development- that's the tail wagging the dog, or looking at the receipt at the restaurant and thinking that's what caused the chef to cook the meal.
> If you have anything relevant to add regarding your hack, post it in the ticket.
Presumably your integration will automatically create a ticket from the TODO. There is already a linting automation, per the original comment. No reason to stop there.
> Presumably your integration will automatically create a ticket from the TODO.
Creating the ticket tracking a work item is known for creating the ticket that tracks work items.
The process is also the epitome of automation, because it requires zero automation to filter TODO items and only requires clicking on a button to create the ticket.
There is no salvageable excuse for this nonsense. Work items are created in tickets. TODO items just track copouts and noise.
The TODO serves as a ticket. If you have to interface with non-developers who can't function without pretty UIs then your automation can duplicate the information into a ticketing system, but otherwise a TODO is all you need; right in the place you want it.
If it is going to be one of those things you never intended to fix, then feel free to not mention it anywhere. Not even a ticketing system benefits from tickets you don't intend to fix. Something you don't intend to fix is noise anywhere it ends up.
A few years ago I used to have an IDE template that was like
// TODO ($username $date)
It was great and a central part of my work flow. I'd just leave them in the code whenever I saw something that needed fixing or could be improved, and every once in a while I'd just grep for this string and get my todos.
Some stuff was urgent, some was to be fixed later. Some never got fixed, but because it was all timestamped, it was easy to identify and clear those out. Also saved my coworkers the git annotate archeology to figure out who wrote the TODO and if they wanted additional context.
This flow felt extremely productive. Being able to just drop these when you think of something reduces the context switching. It also becomes an implicit bookmark as to the code the remark applies to (unlike jiras that are typically not well integrated into the code). Creating a jira is either an expensive context switch, or something you postpone and typically forget when you're done with the task and even if you don't, you've wasted a lot of cognitive energy keeping this in the back of your head all day.
Moved to a project that was incompatible with the IDE I was using. The new IDE lacked solid support for ad hoc named templates and provided no suitable tools for monitoring grep patterns.
I like both at the same time. A TODO and an issue, and the Todo has a link to the issue, and the issue had a permalink to the TODO line. Sometimes the TODO gets done during a refactor or otherwise, so having the comment with a link ensures the corresponding issue gets closed.
Yeah, this is how most of the teams I've worked on have done things. `TODO` is only allowed when accompanied by a link to a ticket, and people are expected to (and do!) enforce this when code reviewing.
It loses too much context in Jira. Could stay permanently beyond the Jira event horizon (since more tickets flow into the Jira than flow out). Or it could get culled in a grooming session ("Haven't seen the bug happen in a while. If someone complains we'll reopen").
Some things can’t be done right now. Maybe the implementation depends on something else that isn’t done yet (perhaps by someone else). And maybe I know exactly where I need to do the work. Then a todo in the comment with a ticket id is better than just a ticket with a completely informal hyperlink to the place in the code where the comment would have been.
Hmmm, I can see why you're doing this. But if you don't trust TODO comments to be useful and/or addressed in a timely manner then having a bunch of Jira tickets won't help you either.
I've made the exact same experience you describe with both tickets and comments. Ancient tickets, somewhere deep in the backlog with cryptic descriptions. Or even better, high prio bugs that never get picked up by the teams. Same with TODOs and FIXMEs.
In both cases it's probably a good idea to just remove the perceived issue after a while. Backlog tickets and todo comments are not like wine, they don't age well. IMO they behave more like compost heaps. :-)
This is why I use FIXME exclusively and always include a constructive description of what needs to be fixed. I sweep through the code before a commit to resolve easy FIXMEs and minimize what ends up in the repository.
I actually wrote "todoinator" that parses out TODO comments from code and presents them to you as a snagging list - we should definitely keep the comments in the code - ideally everything is in code not JIRA where it really just gets lost or fought over by non-coders (treat anything that is not code as "artists impression" of future state).
I like the suggestion to convert a TODO comment into a JIRA action, or supplement the former with the latter. This permits paying attention only to the TODOs, and to discuss them and to prioritize them without first having to run a monster grep job.
Either just do it, or put a work item in the place where you actually track work (Jira or equivalent) so it has at least a chance of getting done. Otherwise you'll end up with the typical 5-to-10 year old TODO comment from a completely different era that helps nobody.
If you're going to leave a comment, leave context around why the hacky solution was chosen at the time of writing, and why you didn't do the "correct" alternative.