4 ms·

Another reason for a system like yours is TODO is just another backlog but one that no one tracks and grows stale. I much prefer either - TODOs are resolved b

by epage 4y ago

Another reason for a system like yours is TODO is just another backlog but one that no one tracks and grows stale. I much prefer either - TODOs are resolved before merge (your FIXME) - TODOs are moved (not copied) to the team backlog (maintaining in both places just gets them out of sync) - TODOs are converted to documentation explaining the approach (e.g. HACKs)

Bedon292 4y ago
I may switch to using FIXME for my personal mid development comments. But I do like having the TODOs maintained with a ticket number in the backlog. Such that you can find the relevant code easily, but there is a ticket and its not forgotten. Especially when it relates to weird behavior in a specific section of code. It also lets people know that that section still needs work when they see it while working in the codebase. Maintain the meat of it in the actual ticket for sure. But `TODO: ABC-123 - brief description` shouldn't really get out of sync. At least hasn't so far for projects I have worked on.
mr-wendel 4y ago
This is absolutely my second system, and one often preferred over my ... um... preferred system :D. In other words, I have my personal bias, but this approach is far easier to scale with a team over time. I still tend to keep the "HACKS" thing though, simply because they localize the documentation right where you need to be aware of it.
codethief 4y ago
4th option: - Create ticket in team backlog and add ticket number to TODO comment (and have CI pipeline check that ticket number is valid)
- epage 4y ago
  You need to check both that its valid and that its still open. Many times I've seen TODOs with issues in code where the issue was closed. Since nothing gates the Issues being closed, you've now broken CI by closing them. Say you do get past that hurdle, you've added friction to the process of managing the backlog because the code now needs to be updated when Issues are rejected. The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue.
  - falcolas 4y ago
    I've done this too (commenting with the ticket # - well, link to ticket), and it's worked quite well for me/us. It's fairly easy to follow the link & check on it, and it can also serve as a tombstone for why a particular issue isn't being addressed.
  - dllthomas 4y ago
    I've been tempted to put issues in the repo, which would solve this problem (and create others).
  - masklinn 4y ago
    > The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue. Makes perfect sense. TODOs are comment, meaning they're as reliable as comments, meaning they often aren't (and the more time passes and code churns around them the less they are).
    - legorobot 4y ago
      Totally agree. I've found that adding a timeline to _remove_ TODOs/DREAMS (whatever the team choice is) from code as a CI check is very applicable -- what you thought might be good at some point in the past may (and likely is) not applicable later down the road! Clean the code, comment actualities later, etc. -- it helps with knowledge share to find ways to make you attend to cleaning things up.
- dllthomas 4y ago
  Something I've built for myself a couple times is the ability to decorate a test with a ticket number so that the test is expected to pass if an environment variable (usually TICKET) is set to that number, and otherwise is expected to fail. I also sometimes include a stricter version that includes a test for the current behavior, on the theory that someone changing the current behavior might be in a good position to fix the ticket.
  - masklinn 4y ago
    > Something I've built for myself a couple times is the ability to decorate a test with a ticket number so that the test is expected to pass if an environment variable (usually TICKET) is set to that number, and otherwise is expected to fail. I don't understand that use case. Do you mean that if you set the envvar, the test now becomes "normal" because the assumption is you're trying to fix the ticket, and thus make the test pass? I guess that makes sense if your workflow is to "clock in" on tickets, to which you can hook env updates?
    - dllthomas 4y ago
      You have it right, although "clock in" sounds a little formal; I'd probably just say "start work".
b3morales 4y ago
> that no one tracks and grows stale On the contrary; since they are right next to the thing that needs work you always encounter them Just In Time. And you can just delete them really easily if you decide they're truly stale. This may not lend itself to planning or management visibility, but for a small private project I prefer them to the overhead of separate tracking.
- drewcoo 4y ago
  > since they are right next to the thing that needs work you always encounter them That means they become scenery, not something in the foreground. They are lost.
- masklinn 4y ago
  > for a small private project I prefer them to the overhead of separate tracking. For a small private project there's no organisation which doesn't work.
  - Wowfunhappy 4y ago
    Actually, I'm increasingly finding that because my work on these types of projects happens sporadically, it's easier for me to get stuck not remembering what I did or need to do. I don't have anything resembling an issue tracker, but I've begun collecting brain dump style notes in either a gist or the Apple notes app.
    - dasz 4y ago
      I'm the same. I fully expect all my side projects to be interrupted / paused for months at a time. This for me this does include a ticketing system, version tracking, rationale documents, wiki etc aren't optional for me. Some of my side projects have more process around them than my work projects because the side projects will definitely get shelved at some point and resumed much later. Future me is always happier when the process was applied.

by epage 4y ago

Bedon292 4y ago

I may switch to using FIXME for my personal mid development comments. But I do like having the TODOs maintained with a ticket number in the backlog. Such that you can find the relevant code easily, but there is a ticket and its not forgotten. Especially when it relates to weird behavior in a specific section of code. It also lets people know that that section still needs work when they see it while working in the codebase. Maintain the meat of it in the actual ticket for sure. But `TODO: ABC-123 - brief description` shouldn't really get out of sync. At least hasn't so far for projects I have worked on.

mr-wendel 4y ago

This is absolutely my second system, and one often preferred over my ... um... preferred system :D. In other words, I have my personal bias, but this approach is far easier to scale with a team over time. I still tend to keep the "HACKS" thing though, simply because they localize the documentation right where you need to be aware of it.

codethief 4y ago

4th option: - Create ticket in team backlog and add ticket number to TODO comment (and have CI pipeline check that ticket number is valid)

epage 4y ago
You need to check both that its valid and that its still open. Many times I've seen TODOs with issues in code where the issue was closed. Since nothing gates the Issues being closed, you've now broken CI by closing them. Say you do get past that hurdle, you've added friction to the process of managing the backlog because the code now needs to be updated when Issues are rejected. The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue.
- falcolas 4y ago
  I've done this too (commenting with the ticket # - well, link to ticket), and it's worked quite well for me/us. It's fairly easy to follow the link & check on it, and it can also serve as a tombstone for why a particular issue isn't being addressed.
- dllthomas 4y ago
  I've been tempted to put issues in the repo, which would solve this problem (and create others).
- masklinn 4y ago
  > The sad part? With almost 10 years on a 20-30 year old code base with many millions of lines of code that are littered with TODOs, I don't think the presence of a TODO was ever helpful when we decided to actually fix an issue. Makes perfect sense. TODOs are comment, meaning they're as reliable as comments, meaning they often aren't (and the more time passes and code churns around them the less they are).
  - legorobot 4y ago
    Totally agree. I've found that adding a timeline to _remove_ TODOs/DREAMS (whatever the team choice is) from code as a CI check is very applicable -- what you thought might be good at some point in the past may (and likely is) not applicable later down the road! Clean the code, comment actualities later, etc. -- it helps with knowledge share to find ways to make you attend to cleaning things up.
dllthomas 4y ago
Something I've built for myself a couple times is the ability to decorate a test with a ticket number so that the test is expected to pass if an environment variable (usually TICKET) is set to that number, and otherwise is expected to fail. I also sometimes include a stricter version that includes a test for the current behavior, on the theory that someone changing the current behavior might be in a good position to fix the ticket.
- masklinn 4y ago
  > Something I've built for myself a couple times is the ability to decorate a test with a ticket number so that the test is expected to pass if an environment variable (usually TICKET) is set to that number, and otherwise is expected to fail. I don't understand that use case. Do you mean that if you set the envvar, the test now becomes "normal" because the assumption is you're trying to fix the ticket, and thus make the test pass? I guess that makes sense if your workflow is to "clock in" on tickets, to which you can hook env updates?
  - dllthomas 4y ago
    You have it right, although "clock in" sounds a little formal; I'd probably just say "start work".

b3morales 4y ago

> that no one tracks and grows stale On the contrary; since they are right next to the thing that needs work you always encounter them Just In Time. And you can just delete them really easily if you decide they're truly stale. This may not lend itself to planning or management visibility, but for a small private project I prefer them to the overhead of separate tracking.

drewcoo 4y ago
> since they are right next to the thing that needs work you always encounter them That means they become scenery, not something in the foreground. They are lost.
masklinn 4y ago
> for a small private project I prefer them to the overhead of separate tracking. For a small private project there's no organisation which doesn't work.
- Wowfunhappy 4y ago
  Actually, I'm increasingly finding that because my work on these types of projects happens sporadically, it's easier for me to get stuck not remembering what I did or need to do. I don't have anything resembling an issue tracker, but I've begun collecting brain dump style notes in either a gist or the Apple notes app.
  - dasz 4y ago
    I'm the same. I fully expect all my side projects to be interrupted / paused for months at a time. This for me this does include a ticketing system, version tracking, rationale documents, wiki etc aren't optional for me. Some of my side projects have more process around them than my work projects because the side projects will definitely get shelved at some point and resumed much later. Future me is always happier when the process was applied.