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.
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.
// TODO: This is fine for now, but if we start handling `bar`s, we’ll need an extra field for `quxx`.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.
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.
Your company should get it's shit together, unless it's in the business of switching ticketing systems.
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.
That is being generous.
Nobody was reading, triaging, or fixing them anyway.
Sometimes comments are useless crap I can deduce from the code but often I actually get some valuable information.
I won't track down a ticket containing the information unless I'm really desperate.
Unfortunately we live in an agile world and there is not a single doc worth its salt.
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.
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.
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.
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.
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
Progress is measured by working software not closed tickets.
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.
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?”
TODO - this would be much cleaner if we merged it with the hash support from target.cc> 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?
This feels like a concern over a nonissue.
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.
A few years ago I used to have an IDE template that was like
// TODO ($username $date)
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.
This added so much friction I stopped doing this.
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. :-)
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.