5 ms·

In no codebase or organisation I've ever worked in were comments actionable information. Some technical debt spans multiple lines, or across files, modules, et

by mfukar 9y ago

In no codebase or organisation I've ever worked in were comments actionable information. Some technical debt spans multiple lines, or across files, modules, etc. Issue trackers are everywhere nowadays. You've found something that needs doing? File an issue. Treat it like any other, it's not special.

maccam94 9y ago
There's different sizes of TODO. For anything beyond small cleanups, yeah, an issue is probably warranted. But, filing tasks in the issue tracker aren't always the best solution either. They often become out of sync with the state of the code, and who's going to trawl through all of those low-priority issues on a regular basis? To mitigate the de-synchronization, I tend to embed links to the issue in the comment like: # TODO: Frob the foobar issue #4376
- mfukar 9y ago
  The only way an issue about technical debt becomes irrelevant is the debt is not there any more. I don't know how others treat an issue tracker; on my team, we go through issues at the start of every sprint and possibly re-prioritise. Issue became irrelevant? Close. Move on.
- dllthomas 9y ago
  > They often become out of sync with the state of the code I try to write a test when I open a ticket, demonstrating the desired behavior, and mark it such that it's checked for failure (so we notice if we've fixed it in passing) unless an environment variable is set to the particular ticket number. Sometimes I also include a test demonstrating current behavior - this helps surface the tickets if someone is working on something related.
bunderbunder 9y ago
Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. The combination solution that really does get you the best of both worlds is to create a ticket, and then reference the ticket # with TODOs when there are bits of the code that are influenced by that technical debt. That way if you're seeing a todo in the code, you can easily get to a central ticket with more information. But also, when you're working on one of those tech debt tickets, you can search for the ticket # in the code base to verify that you really have found all known (by which I mean, somebody cared enough to make a note of it) places where the tech debt is manifesting itself in the code. Also, tech debt is less likely to become a dead letter. Programmers read the code incidentally to their work. The only people who habitually read the ticket queue incidentally to their work have PMO certifications.
- mfukar 9y ago
  > Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. I used to think the same; however the reality is if nobody cares about a given issue it's not an issue worth working on. Same with TODO or other notes in comments.
  - bunderbunder 9y ago
    There are many reasons to not work on something immediately beyond "nobody cares". I've frequently run into situations where some small hack needed to be used to work around a shortcoming in some major module. Fixing that module might not be something that can be done right away, either due to scheduling or resource constraints, or because that module's owned by some other team, or it's a 3rd-party component, or whatever. When that thing finally does get fixed or upgraded, it sure is nice to be able to just look up the master ticket for "Hacks to work around X" and easily find all the little things you can clean up right away. But, of course, if your tooling and team procedures force you to choose between "fix immediately" and "DFC", I suppose that would result in a lot of decisions to not even worry about technical debt. Over time, you could probably even lull yourself into thinking it was never technical debt in the first place.
    - mfukar 9y ago
      > There are many reasons to not work on something immediately beyond "nobody cares"...[snip] I agree. That is not what I said.
deleted 9y ago
[deleted]
ryandrake 9y ago
+1 for using the issue tracker. Creating a new issue in your tracker should be close to zero effort (if it's not, your company has a bigger problem than technical debt). And I would imagine in the vast majority of dev shops nowadays, you always need to cite an issue when you commit your code, so why not create it as soon as you identify the technical debt?
hinkley 9y ago
Putting things in the bug database is officially transferring responsibility for the issue to the management or the team. Give me permission to work on this thing. It's a cop-out, and unfortunately a hallmark of a class of developer most of us miss. It took working with roughly the same group of people for four+ years, twice, before I even noticed them. It's probably two groups with similar symptoms which I think contributed to my confusion. First group are the fakers. They are people who want to appear high minded and will agree with all of your plans for reducing tech debt, except the first time there is any schedule tightness they'll throw it all away and claim that they wanted to do more, But The Deadline. You can spot these people because the next time there is schedule slack due to requirements not being ready, they will complain about there not being anything to do. Meanwhile their legitimately conscientious peers are already 12 hours into some refactor that the boss didn't tell them not to work on. The second are Flow junkies. There are people on your team that do heavy lifting. Big rework, new architecture, they can do amazing things, occasionally startlingly fast (doing judo on the code to make it do things you didn't think it could). Problem is, they are so addicted to The Flow that they have to wrestle dragons even if they don't exist. They can take the code far in directions nobody else understands, which must be because they are smart and you feel a little imposter syndrome. But what really happens is that they make the code in their own mental image because they can, and that stacks the deck so that they are >3x more productive in that code than everybody else. This creates the 10x myth, because they are actually about 3x more productive in arbitrary code, but 10x more productive in code they've arranged so only they can really follow it. In the middle of the Flow stopping to clean up pesky things like argument consistency might break the Flow, Their tell is that they often "don't have time" to fix annoying inconsistencies or bugs in their code, expecting people to avoid them, and yet they seem to have plenty of time to reinvent the wheel, writing frameworks or event processing systems when we already have tons of those to chose from. Because those Big Problems have the sort of time and space in them to both require and allow for a Flow State to happen. I know this type because I'm an ex Flow junkie. I spent too much time studying ergonomics and realized that just because I could follow the code easily didn't mean it was great code. Though I could achieve Flow while doing truly annoying bookkeeping refractors, over a long period of time I found it harder to achieve the Flow state. Maybe I got old or maybe I was less motivated or maybe open offices killed it, who knows, So I subscribed to the philosophy of, "a rising tide lifts all boats", and am just fine being a 3x developer who makes the code and process more productive for others.

by mfukar 9y ago

maccam94 9y ago

There's different sizes of TODO. For anything beyond small cleanups, yeah, an issue is probably warranted. But, filing tasks in the issue tracker aren't always the best solution either. They often become out of sync with the state of the code, and who's going to trawl through all of those low-priority issues on a regular basis? To mitigate the de-synchronization, I tend to embed links to the issue in the comment like: # TODO: Frob the foobar issue #4376

mfukar 9y ago
The only way an issue about technical debt becomes irrelevant is the debt is not there any more. I don't know how others treat an issue tracker; on my team, we go through issues at the start of every sprint and possibly re-prioritise. Issue became irrelevant? Close. Move on.
dllthomas 9y ago
> They often become out of sync with the state of the code I try to write a test when I open a ticket, demonstrating the desired behavior, and mark it such that it's checked for failure (so we notice if we've fixed it in passing) unless an environment variable is set to the particular ticket number. Sometimes I also include a test demonstrating current behavior - this helps surface the tickets if someone is working on something related.

bunderbunder 9y ago

Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. The combination solution that really does get you the best of both worlds is to create a ticket, and then reference the ticket # with TODOs when there are bits of the code that are influenced by that technical debt. That way if you're seeing a todo in the code, you can easily get to a central ticket with more information. But also, when you're working on one of those tech debt tickets, you can search for the ticket # in the code base to verify that you really have found all known (by which I mean, somebody cared enough to make a note of it) places where the tech debt is manifesting itself in the code. Also, tech debt is less likely to become a dead letter. Programmers read the code incidentally to their work. The only people who habitually read the ticket queue incidentally to their work have PMO certifications.

mfukar 9y ago
> Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. I used to think the same; however the reality is if nobody cares about a given issue it's not an issue worth working on. Same with TODO or other notes in comments.
- bunderbunder 9y ago
  There are many reasons to not work on something immediately beyond "nobody cares". I've frequently run into situations where some small hack needed to be used to work around a shortcoming in some major module. Fixing that module might not be something that can be done right away, either due to scheduling or resource constraints, or because that module's owned by some other team, or it's a 3rd-party component, or whatever. When that thing finally does get fixed or upgraded, it sure is nice to be able to just look up the master ticket for "Hacks to work around X" and easily find all the little things you can clean up right away. But, of course, if your tooling and team procedures force you to choose between "fix immediately" and "DFC", I suppose that would result in a lot of decisions to not even worry about technical debt. Over time, you could probably even lull yourself into thinking it was never technical debt in the first place.
  - mfukar 9y ago
    > There are many reasons to not work on something immediately beyond "nobody cares"...[snip] I agree. That is not what I said.

deleted 9y ago

[deleted]

ryandrake 9y ago

+1 for using the issue tracker. Creating a new issue in your tracker should be close to zero effort (if it's not, your company has a bigger problem than technical debt). And I would imagine in the vast majority of dev shops nowadays, you always need to cite an issue when you commit your code, so why not create it as soon as you identify the technical debt?

hinkley 9y ago

Putting things in the bug database is officially transferring responsibility for the issue to the management or the team. Give me permission to work on this thing. It's a cop-out, and unfortunately a hallmark of a class of developer most of us miss. It took working with roughly the same group of people for four+ years, twice, before I even noticed them. It's probably two groups with similar symptoms which I think contributed to my confusion. First group are the fakers. They are people who want to appear high minded and will agree with all of your plans for reducing tech debt, except the first time there is any schedule tightness they'll throw it all away and claim that they wanted to do more, But The Deadline. You can spot these people because the next time there is schedule slack due to requirements not being ready, they will complain about there not being anything to do. Meanwhile their legitimately conscientious peers are already 12 hours into some refactor that the boss didn't tell them not to work on. The second are Flow junkies. There are people on your team that do heavy lifting. Big rework, new architecture, they can do amazing things, occasionally startlingly fast (doing judo on the code to make it do things you didn't think it could). Problem is, they are so addicted to The Flow that they have to wrestle dragons even if they don't exist. They can take the code far in directions nobody else understands, which must be because they are smart and you feel a little imposter syndrome. But what really happens is that they make the code in their own mental image because they can, and that stacks the deck so that they are >3x more productive in that code than everybody else. This creates the 10x myth, because they are actually about 3x more productive in arbitrary code, but 10x more productive in code they've arranged so only they can really follow it. In the middle of the Flow stopping to clean up pesky things like argument consistency might break the Flow, Their tell is that they often "don't have time" to fix annoying inconsistencies or bugs in their code, expecting people to avoid them, and yet they seem to have plenty of time to reinvent the wheel, writing frameworks or event processing systems when we already have tons of those to chose from. Because those Big Problems have the sort of time and space in them to both require and allow for a Flow State to happen. I know this type because I'm an ex Flow junkie. I spent too much time studying ergonomics and realized that just because I could follow the code easily didn't mean it was great code. Though I could achieve Flow while doing truly annoying bookkeeping refractors, over a long period of time I found it harder to achieve the Flow state. Maybe I got old or maybe I was less motivated or maybe open offices killed it, who knows, So I subscribed to the philosophy of, "a rising tide lifts all boats", and am just fine being a 3x developer who makes the code and process more productive for others.