5 ms·

> This is a good way to loose valuable knowledge. It really isn't. If you have anything relevant to add regarding your hack, post it in the ticket. That's the

> This is a good way to loose valuable knowledge. 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.

nsxwolf 4y ago
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.
- simplotek 4y ago
  > I'm certainly not opening JIRA for it, so (...) 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.
  - wtetzner 4y ago
    Or it could be useful context for the next person to modify the code. Maybe it’s something that is only worth doing under certain conditions? // TODO: This is fine for now, but if we start handling `bar`s, we’ll need an extra field for `quxx`.
    - UncleMeat 4y ago
      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.
      - wtetzner 4y ago
        And if the reason bars aren’t implemented yet is because nobody requested it, then there is no tracking ticket.
  - lmm 4y ago
    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.
- lazyasciiart 4y ago
  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.
  - simplotek 4y ago
    > 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.
    - lazyasciiart 4y ago
      I explicitly said it would be a separate code review. Not every change needs a ticket, and the idea that it does is a barrier to improving code.
    - sdiupIGPWEfh 4y ago
      > instead track work on a ticket 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.
bodangly 4y ago
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.
- simplotek 4y ago
  > 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.
  - lazyasciiart 4y ago
    Really? My company is on its third ticketing system.
    - simplotek 4y ago
      > Really? My company is on its third ticketing system. Your company should get it's shit together, unless it's in the business of switching ticketing systems.
      - bluGill 4y ago
        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.
randomdata 4y ago
> 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.
- simplotek 4y ago
  > 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.
  - randomdata 4y ago
    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.
lifeisstillgood 4y ago
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
- monkpit 4y ago
  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.
  - lifeisstillgood 4y ago
    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.
  - sdiupIGPWEfh 4y ago
    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.
- simplotek 4y ago
  > 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.
deleted 4y ago
[deleted]
eyelidlessness 4y ago
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?”
convolvatron 4y ago
you really have this all figured out don't you. I use TODOs for structural changes, not for stuff that I know has obvious flaws. TODO - this would be much cleaner if we merged it with the hash support from target.cc
mopsi 4y ago
>> 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.
- UncleMeat 4y ago
  > sold, sublicensed or open-sourced. 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.

nsxwolf 4y ago

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.

simplotek 4y ago
> I'm certainly not opening JIRA for it, so (...) 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.
- wtetzner 4y ago
  Or it could be useful context for the next person to modify the code. Maybe it’s something that is only worth doing under certain conditions? // TODO: This is fine for now, but if we start handling `bar`s, we’ll need an extra field for `quxx`.
  - UncleMeat 4y ago
    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.
    - wtetzner 4y ago
      And if the reason bars aren’t implemented yet is because nobody requested it, then there is no tracking ticket.
- lmm 4y ago
  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.
lazyasciiart 4y ago
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.
- simplotek 4y ago
  > 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.
  - lazyasciiart 4y ago
    I explicitly said it would be a separate code review. Not every change needs a ticket, and the idea that it does is a barrier to improving code.
  - sdiupIGPWEfh 4y ago
    > instead track work on a ticket 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.

bodangly 4y ago

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.

simplotek 4y ago
> 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.
- lazyasciiart 4y ago
  Really? My company is on its third ticketing system.
  - simplotek 4y ago
    > Really? My company is on its third ticketing system. Your company should get it's shit together, unless it's in the business of switching ticketing systems.
    - bluGill 4y ago
      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.

randomdata 4y ago

> 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.

simplotek 4y ago
> 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.
- randomdata 4y ago
  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.

lifeisstillgood 4y ago

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

monkpit 4y ago
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.
- lifeisstillgood 4y ago
  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.
- sdiupIGPWEfh 4y ago
  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.
simplotek 4y ago
> 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.

deleted 4y ago

[deleted]

eyelidlessness 4y ago

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?”

convolvatron 4y ago

you really have this all figured out don't you. I use TODOs for structural changes, not for stuff that I know has obvious flaws. TODO - this would be much cleaner if we merged it with the hash support from target.cc

mopsi 4y ago

>> 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.

UncleMeat 4y ago
> sold, sublicensed or open-sourced. 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.