6 ms·

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

by mjr00 4y ago

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.

davidmurdoch 4y ago
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.
- saghm 4y ago
  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.
quonn 4y ago
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.
- rhaway84773 4y ago
  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.
  - lamontcg 4y ago
    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.
- simplotek 4y ago
  > 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.
- UncleMeat 4y ago
  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.
marginalia_nu 4y ago
Depends on how you use it. 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.
- nurbel 4y ago
  Sounds like you had a workflow that you felt and still feel good about, why did you stop doing it?
  - marginalia_nu 4y ago
    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. This added so much friction I stopped doing this.
mrkeen 4y ago
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").
civopsec 4y ago
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.
lifeisstillgood 4y ago
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).
kevin_thibedeau 4y ago
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.
simmschi 4y ago
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. :-)
jll29 4y ago
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.
wtetzner 4y ago
I do both: put a TODO in the code with a ticket number. // TODO (<ticket-number>): Foo should be frobnicated
gumby 4y ago
A TODO is often a kind of explanation of a "Chesterton's fence" situation.

by mjr00 4y ago

davidmurdoch 4y ago

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.

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

quonn 4y ago

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.

rhaway84773 4y ago
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.
- lamontcg 4y ago
  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.
simplotek 4y ago
> 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.
UncleMeat 4y ago
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.

marginalia_nu 4y ago

Depends on how you use it. 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.

nurbel 4y ago
Sounds like you had a workflow that you felt and still feel good about, why did you stop doing it?
- marginalia_nu 4y ago
  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. This added so much friction I stopped doing this.

mrkeen 4y ago

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

civopsec 4y ago

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.

lifeisstillgood 4y ago

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

kevin_thibedeau 4y ago

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.

simmschi 4y ago

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

jll29 4y ago

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.

wtetzner 4y ago

I do both: put a TODO in the code with a ticket number. // TODO (<ticket-number>): Foo should be frobnicated

gumby 4y ago

A TODO is often a kind of explanation of a "Chesterton's fence" situation.