4 ms·

I've been thinking quite a bit about the topic, and I still think having tech debt issues documented as code comments is better than in an issue tracker. You wi

I've been thinking quite a bit about the topic, and I still think having tech debt issues documented as code comments is better than in an issue tracker. You will get more contact with the issues than if they're buried in a backlog I wrote a bit about what was going on in my head here, if you're interested: https://isidoro.io/writing/tech-debt-broken-windows/ https://isidoro.io/writing/tech-debt-broken-windows/

rakoo 7y ago
While it's true that we spend more time in the code than in issue trackers, the advantage of the issue trackers is that a discussion can happen with arguments on both sides and a final decision can be taken, along with a plan to do it. Every time I see a conversation in comments like this: // TODO (mr): Make this more generic // rp: we only use it once, why change it ? // ol: I agree with rp It feels too weird to leave in place. Should I add a comment with my point of view ? If the function in question is modified such that the comments are invalid, should I delete the comments ? Leave them for "documentation" ?
- sergioisidoro 7y ago
  That's a very valid point. I was thinking from the perspective of the people contracting the debt. Usually you know what you would need to do if you had time and resources. But yes, for finding existing and uncharted tech debt items, and deciding on their future, the discussion should happen somewhere else.
yourapostasy 7y ago
I've always wondered about other people's experiences with backlogs. In all of the client accounts I've been to, a backlog was at the end of the day, simply leadership acknowledgement that there exists more work to do than there is budget to do it, and the backlog really should be mostly the last stage of an issue triage. I wonder if any organizations would benefit from the effort to maintain an officially-recognized triage list of "we have to let these remediations die" issues, instead of a backlog. Once issues make it into a backlog and stay there for longer than T time (usually about a year), I've very rarely seen the issue make it out of the backlog into a sprint again, even years later. At that point, it makes more sense to write up these issues into an architecture document that explicitly acknowledges the technical debt as the cost of doing business around the codebase while relating context to the rest of the architecture, and work up a systematic way to track the technical debt. And track the estimated effort that goes into working around each item in that list in the sense of, "if I didn't have to work around this debt, and it was fixed in the manner noted, I estimate it would take me -T time to complete this task instead". At least that way leadership gets a sense of the actual cost of carrying specific pieces of debt around over time instead of only being able to evaluate acute debt. It might be acceptable to pay an estimated 100 hours per year for one item indefinitely, while for another similar item the underlying business mechanics makes it worthwhile to fix it now than let it accumulate over a 5 year schedule.
- gen220 7y ago
  At my current place of work, we‘ve been experimenting with two-week “sprints” (hate the term but it’s standard, so bear with me!). We spend half of the off-week sprint planning session “pruning” the backlog: pointing and discussing new tickets, and refactoring or deleting the oldest tickets. If the second half of anyone’s sprint fees thin, we add a ticket (more or less of their choice) from the backlog to their sprint. I kind of like this system, because it allows you to think in cycles both longer and shorter than the sprint. If I see some fun optimization, but know I won’t be able to fit it into my sprint, I can craft a well-documented ticket in confidence that someone will have fun getting to take care of it in the future. Backlog tickets are also a fantastic way to onboard new engineers, because the tickets come from all corners of our system: from infrastructure upgrades to copy changes. Of course this system only works as long as you have disciplined engineers. Bad tickets will drown this system. But the “checkpoint” every other week has really been all we’ve needed to keep quality consistently high.
- sergioisidoro 7y ago
  I completely agree with what you said. But tech debt, at least for me, feels very different from the tasks that should be triaged. It's very uncommon that we allocate time to repay certain debt, so does it make sense to triage and/or backlog? That was mainly my point with previous comment. My experience is more like doing some other task, coming across some tech debt, and repaying it on the spot if I'm not that constrained by time. For paying debt on the spot having a clearly flagged issue and proposed resolution would likely help me navigating and avoiding known caveats, and get a fix faster. Even if I don't have time to fix the issue in the spot, knowing the reason why things are like they are might help with my morale and be less frustrated with coworkers. But you mentioned a systematic way of tracking tech debt and the cost of each item per year. How is that different from a backlog after a while?
  - PretzelFisch 7y ago
    From a lead, product manager position yes. When I know what is coming down the pipe I can push the rework backlog items in a prior sprint, so that things don't get difficult for the following sprints feature set. It does work assuming my pipeline is consistent and not at a tail chasing stage.
PretzelFisch 7y ago
well if your code base was like mine you would have //BUG:1234 littered everywhere so no need to not use the tracker.
hinkley 7y ago
If handled maturely, TODOs can be written permission to other devs to make wholesale changes to parts of code you wrote without any social awkwardness. When I was young and had a smaller toolbox, refactoring was right at the top, and people ended up “giving” me modules they had written because within a few months they didn’t recognize their code anymore (especially if they were busy elsewhere). It was great for my professional development, at first, but a developer’s scale is limited to how many responsibilities they can juggle. Older me, with a larger toolbox, also sees that maybe there weren’t so happy to hand over their work like that. Don’t fix absolutely everything that you know how to fix. Leave people hungry for more. That invites new contributors and keeps the old ones engaged for longer. I had a good friend in college who was a Lit major and so I got a steady stream, sometimes direct, other times by osmosis, of motivational philosophy for creatives. Apparently Hemingway, in an interview about how to maintain momentum, said you should stop writing when you know what happens next. When you pick it up again you always have something you know how to do. If someone else beats you to it, then they end up with more ownership of that code, allowing you to focus on other things.

rakoo 7y ago

While it's true that we spend more time in the code than in issue trackers, the advantage of the issue trackers is that a discussion can happen with arguments on both sides and a final decision can be taken, along with a plan to do it. Every time I see a conversation in comments like this: // TODO (mr): Make this more generic // rp: we only use it once, why change it ? // ol: I agree with rp It feels too weird to leave in place. Should I add a comment with my point of view ? If the function in question is modified such that the comments are invalid, should I delete the comments ? Leave them for "documentation" ?

sergioisidoro 7y ago
That's a very valid point. I was thinking from the perspective of the people contracting the debt. Usually you know what you would need to do if you had time and resources. But yes, for finding existing and uncharted tech debt items, and deciding on their future, the discussion should happen somewhere else.

yourapostasy 7y ago

I've always wondered about other people's experiences with backlogs. In all of the client accounts I've been to, a backlog was at the end of the day, simply leadership acknowledgement that there exists more work to do than there is budget to do it, and the backlog really should be mostly the last stage of an issue triage. I wonder if any organizations would benefit from the effort to maintain an officially-recognized triage list of "we have to let these remediations die" issues, instead of a backlog. Once issues make it into a backlog and stay there for longer than T time (usually about a year), I've very rarely seen the issue make it out of the backlog into a sprint again, even years later. At that point, it makes more sense to write up these issues into an architecture document that explicitly acknowledges the technical debt as the cost of doing business around the codebase while relating context to the rest of the architecture, and work up a systematic way to track the technical debt. And track the estimated effort that goes into working around each item in that list in the sense of, "if I didn't have to work around this debt, and it was fixed in the manner noted, I estimate it would take me -T time to complete this task instead". At least that way leadership gets a sense of the actual cost of carrying specific pieces of debt around over time instead of only being able to evaluate acute debt. It might be acceptable to pay an estimated 100 hours per year for one item indefinitely, while for another similar item the underlying business mechanics makes it worthwhile to fix it now than let it accumulate over a 5 year schedule.

gen220 7y ago
At my current place of work, we‘ve been experimenting with two-week “sprints” (hate the term but it’s standard, so bear with me!). We spend half of the off-week sprint planning session “pruning” the backlog: pointing and discussing new tickets, and refactoring or deleting the oldest tickets. If the second half of anyone’s sprint fees thin, we add a ticket (more or less of their choice) from the backlog to their sprint. I kind of like this system, because it allows you to think in cycles both longer and shorter than the sprint. If I see some fun optimization, but know I won’t be able to fit it into my sprint, I can craft a well-documented ticket in confidence that someone will have fun getting to take care of it in the future. Backlog tickets are also a fantastic way to onboard new engineers, because the tickets come from all corners of our system: from infrastructure upgrades to copy changes. Of course this system only works as long as you have disciplined engineers. Bad tickets will drown this system. But the “checkpoint” every other week has really been all we’ve needed to keep quality consistently high.
sergioisidoro 7y ago
I completely agree with what you said. But tech debt, at least for me, feels very different from the tasks that should be triaged. It's very uncommon that we allocate time to repay certain debt, so does it make sense to triage and/or backlog? That was mainly my point with previous comment. My experience is more like doing some other task, coming across some tech debt, and repaying it on the spot if I'm not that constrained by time. For paying debt on the spot having a clearly flagged issue and proposed resolution would likely help me navigating and avoiding known caveats, and get a fix faster. Even if I don't have time to fix the issue in the spot, knowing the reason why things are like they are might help with my morale and be less frustrated with coworkers. But you mentioned a systematic way of tracking tech debt and the cost of each item per year. How is that different from a backlog after a while?
- PretzelFisch 7y ago
  From a lead, product manager position yes. When I know what is coming down the pipe I can push the rework backlog items in a prior sprint, so that things don't get difficult for the following sprints feature set. It does work assuming my pipeline is consistent and not at a tail chasing stage.

PretzelFisch 7y ago

well if your code base was like mine you would have //BUG:1234 littered everywhere so no need to not use the tracker.

hinkley 7y ago

If handled maturely, TODOs can be written permission to other devs to make wholesale changes to parts of code you wrote without any social awkwardness. When I was young and had a smaller toolbox, refactoring was right at the top, and people ended up “giving” me modules they had written because within a few months they didn’t recognize their code anymore (especially if they were busy elsewhere). It was great for my professional development, at first, but a developer’s scale is limited to how many responsibilities they can juggle. Older me, with a larger toolbox, also sees that maybe there weren’t so happy to hand over their work like that. Don’t fix absolutely everything that you know how to fix. Leave people hungry for more. That invites new contributors and keeps the old ones engaged for longer. I had a good friend in college who was a Lit major and so I got a steady stream, sometimes direct, other times by osmosis, of motivational philosophy for creatives. Apparently Hemingway, in an interview about how to maintain momentum, said you should stop writing when you know what happens next. When you pick it up again you always have something you know how to do. If someone else beats you to it, then they end up with more ownership of that code, allowing you to focus on other things.