8 ms·

I wish there was a way to leave a comment like // todo(gravypod, techdebt): some description of the issue and have that, when pushed up to a VCS, turn int

I wish there was a way to leave a comment like // todo(gravypod, techdebt): some description of the issue and have that, when pushed up to a VCS, turn into an issue created, assigned to me, and labeled with tech debt. I know this exists in some of the walled gardens like Google's internal infrastructure but I think if this existed in the open world you'd see a lot more consistency between issues/comments and you'd enable more continual cleanup. My guess is, in some less healthy organizations, tech debt comments get cleaned up more frequently than tech debt issues. Issues probably don't get assigned (a practice I have experienced at many companies) but comments are "right there" and can be rolled into other tickets in an attempt to always leave it cleaner than you've found it.

jbergstroem 7y ago
There are github actions to help out here. I use the todo "bot" that marks up todo comments you would create in PR's or otherwise into issues. You can for instance assign yourself/someone and change how you want it labelled. https://github.com/marketplace/todo https://github.com/marketplace/todo is one of them.
- gravypod 7y ago
  That's neat. I never knew this existed. Unfortunately I mainly use Gitlab wherever I work.
  - gbear605 7y ago
    I don’t know much about git hooks, but I think that it would be fairly simple to wrote a small one that parses the changes for the todo comment and then calls to Gitlab’s API. Double points for closing the ticket if the todo comment is removed.
    - gravypod 7y ago
      Doing it client side might make it hard to do things like accepting MRs from forks.
    - deadbunny 7y ago
      You could probably do it with a Gitlab CI step + python (or whatever language of choice) script as well.
  - antsar 7y ago
    There's an issue for this in GitLab's tracker: https://gitlab.com/gitlab-org/gitlab/-/issues/14259 https://gitlab.com/gitlab-org/gitlab/-/issues/14259 Sadly, it's four years old and seems pretty stagnant.
    - samanthalee233 7y ago
      Hey there, I'm a GitLab community advocate, just wanted to thank you for brining attention to this issue, our team commented to get the conversation moving today: https://gitlab.com/gitlab-org/gitlab/-/issues/14259#note_327134034 https://gitlab.com/gitlab-org/gitlab/-/issues/14259#note_327...
    - gravypod 7y ago
      It's unfortunate gitlab is built as a monolith. I'd be very capable of writing the code for implementing such a feature myself if gitlab had a first class API. The code, as we all know, would look something like this: for commit diff = commit.diff for line in diff.result if 'todo' in line line_id = hash(line) if existing := issues.find(tags={'todo_id': line_id}): existing.update(code_url = new line location) else: issues.create(....) But because these APIs aren't first class a change like this requires deep knowledge of gitlab's internals and acceptance and prioritization of features from gitlab's core team.
sergioisidoro 7y ago
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.
cjfd 7y ago
While very occasionally useful I think technical debt issues mostly should not exist. Improving code quality should be considered part of any issue that a person takes up. Any code that relates to the issue should also be viewed as a potential candidate for refactoring as a part of that same issue. Notice also that in TDD refactoring is part of the TDD cycle: write test, write code, refactor. Doing TDD would make you do what is described in the previous paragraph as part of the cycle. So generally one would refactor something multiple times a day.
- gravypod 7y ago
  The ticket serves as a communication point and a cost estimate tool. Even if the tasks are never explicitly assigned they are very useful. That's why I'd like a comment ticket linkage system. Support the positives of both usages by automating everything.
  - techbio 7y ago
    I could see this showing up in a near-future version of GitHub, along with enhanced default logging views.
- 0xEFF 7y ago
  In practice this results in too much time spent “cleaning up” and not enough time delivering business value. Hence why tech debt tickets are valuable, they allow the business to decide when to spend time on them.
  - sooheon 7y ago
    Yes, debts which need to be paid off immediately hardly serve their purpose.
  - karatestomp 7y ago
    It’s really hard to convey tech debt cost. Probably many systems have a ton of problems adding 5% to every feature here, 10% there, bad DB design from early in the project that makes a bunch of actions far riskier than they should be (but until it breaks several times no-one cares and if your devs are putting 3x as much effort into those dangerous operations and know what they’re doing, it won’t), and so on. Communicating that in a way the business folks will care about is hard, and the full costs are difficult to account for. [edit] hell, communicating that in a way the weaker end of technical managers will care about can be hard, for that matter. If they came up “doing it wrong” and are of a certain mindset, good friggin’ luck.
archi42 7y ago
Hm, at $job we're already sending all git commits to a Bugzilla (no bug in commit comment => push is rejected). Parsing the comment or diff for these instructions shouldn't be too difficult. Though we have several products + subproducts defined in Bugzilla (that's why we can't easily migrate to more modern solutions). Not sure if there is this can be easily mapped automagically. Also, keeping track if the comment is moved around, especially if slightly altered with the same commit, might be less straight-forward. Also merges might be a pain. Could also be done for those chancy subtask/checkboxes gitlab and github offer (and which I really miss in bugzilla).
efnx 7y ago
I created srcoftruth.com for this reason, but it's a hobby project - and I'm currently rebuilding it.
caseymarquis 7y ago
Sounds pretty doable at the most basic level. Spin up a small server or use your PC, make a daemon/service which pulls your master branch in once every 15 seconds. From there you can either parse new changes on your own, or likely use hooks in git. Just parse the files for your syntax, likely using some kind of manual per page uid. From here, I would send an email into our system, as no api or credentials are needed, and we already have that set up. Using an api wouldn't be that much more work. Sounds like a fun project. The complication is that information is now in two places. So the next step is to use your tracker api to create an issue, and get the url to it. Then replace the comment in the code with the url and make an automated commit/push. Still all seems very doable and fun.
Tyr42 7y ago
Google's "infrastructure" is just people asking you to make a bug (issue) and put // TODO(b/<bug number>): Fix this up during code review. Sometimes I'll just put TODO(<username>) if I don't really care about keeping an eye on it.
- gravypod 7y ago
  It's too bad those tickets aren't created automatically. That probably raises the bar for people wanting to add these sorts of comments.
MAGZine 7y ago
I've already built a little tooling around pull requests and git commits at autodesk and so when I read this, I thought, oh, yeah, that's a great idea, I should do that. But here's the thing. Our team already has a policy for TODOs: either you open a ticket and leave the ticket number in the code, or you do not leave a todo at all. This way, we're never guessing which ticket belong to which todo, and all of the necessary context (including what spawned the todo, why it may or may not have been a good idea, etc) can be present with the code. I think in this case, the policy is a better system than just randomly opening tickets. It increases the barrier to entry if you are going to leave a TODO (versus leaving it out or just not being lazy and doing it), and prevents the backlog from needing even more grooming.
- gravypod 7y ago
  > It increases the barrier to entry if you are going to leave a TODO (versus leaving it out or just not being lazy and doing it), and prevents the backlog from needing even more grooming I would rather have many tickets that specify actual work than a lot of work specified in no tickets. Using monotony as a filter doesn't sound like it would lower defect rates over long periods of time.
  - MAGZine 7y ago
    Conversely, it actually serves as a reminder for you to prioritize the work rather than coming across and old todo as a happenchance, when you're not in the frame of mind or have the time to fix it. Yes, it's tedium. But it's necessary tedium. It's documentation.
Groxx 7y ago
I've taken to adding a small linter: TODOs must have a date attached, and after that date they'll fail a (fast, skippable) lint job. My goal isn't to require tackling them, merely to make them annoying enough to prioritize. So far it has worked out pretty well - within a day or three of a deadline passing, about half the time the date gets bumped a month and a task is made for the next sprint, a third it's just fixed, and the remainder are no longer relevant so they're just deleted.
- sergioisidoro 7y ago
  This is a great idea. I think I might do the same. Thanks!
jpswade 7y ago
My rule is that a todo should have a way to get to done. If it’s important enough to write a todo then it’s probably worth doing and prioritising against everything else.
- nightfly 7y ago
  Eh, that's a bit extreme. If I write a todo in code rather than just doing it, it's because I've already made the decision that it's not important/needed enough to do now.
deleted 7y ago
[deleted]
hashhar 7y ago
RedHat has a maven plugin for this. Let me see if I can ask someone to share more details.

jbergstroem 7y ago

There are github actions to help out here. I use the todo "bot" that marks up todo comments you would create in PR's or otherwise into issues. You can for instance assign yourself/someone and change how you want it labelled. https://github.com/marketplace/todo https://github.com/marketplace/todo is one of them.

gravypod 7y ago
That's neat. I never knew this existed. Unfortunately I mainly use Gitlab wherever I work.
- gbear605 7y ago
  I don’t know much about git hooks, but I think that it would be fairly simple to wrote a small one that parses the changes for the todo comment and then calls to Gitlab’s API. Double points for closing the ticket if the todo comment is removed.
  - gravypod 7y ago
    Doing it client side might make it hard to do things like accepting MRs from forks.
  - deadbunny 7y ago
    You could probably do it with a Gitlab CI step + python (or whatever language of choice) script as well.
- antsar 7y ago
  There's an issue for this in GitLab's tracker: https://gitlab.com/gitlab-org/gitlab/-/issues/14259 https://gitlab.com/gitlab-org/gitlab/-/issues/14259 Sadly, it's four years old and seems pretty stagnant.
  - samanthalee233 7y ago
    Hey there, I'm a GitLab community advocate, just wanted to thank you for brining attention to this issue, our team commented to get the conversation moving today: https://gitlab.com/gitlab-org/gitlab/-/issues/14259#note_327134034 https://gitlab.com/gitlab-org/gitlab/-/issues/14259#note_327...
  - gravypod 7y ago
    It's unfortunate gitlab is built as a monolith. I'd be very capable of writing the code for implementing such a feature myself if gitlab had a first class API. The code, as we all know, would look something like this: for commit diff = commit.diff for line in diff.result if 'todo' in line line_id = hash(line) if existing := issues.find(tags={'todo_id': line_id}): existing.update(code_url = new line location) else: issues.create(....) But because these APIs aren't first class a change like this requires deep knowledge of gitlab's internals and acceptance and prioritization of features from gitlab's core team.

sergioisidoro 7y ago

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.

cjfd 7y ago

While very occasionally useful I think technical debt issues mostly should not exist. Improving code quality should be considered part of any issue that a person takes up. Any code that relates to the issue should also be viewed as a potential candidate for refactoring as a part of that same issue. Notice also that in TDD refactoring is part of the TDD cycle: write test, write code, refactor. Doing TDD would make you do what is described in the previous paragraph as part of the cycle. So generally one would refactor something multiple times a day.

gravypod 7y ago
The ticket serves as a communication point and a cost estimate tool. Even if the tasks are never explicitly assigned they are very useful. That's why I'd like a comment ticket linkage system. Support the positives of both usages by automating everything.
- techbio 7y ago
  I could see this showing up in a near-future version of GitHub, along with enhanced default logging views.
0xEFF 7y ago
In practice this results in too much time spent “cleaning up” and not enough time delivering business value. Hence why tech debt tickets are valuable, they allow the business to decide when to spend time on them.
- sooheon 7y ago
  Yes, debts which need to be paid off immediately hardly serve their purpose.
- karatestomp 7y ago
  It’s really hard to convey tech debt cost. Probably many systems have a ton of problems adding 5% to every feature here, 10% there, bad DB design from early in the project that makes a bunch of actions far riskier than they should be (but until it breaks several times no-one cares and if your devs are putting 3x as much effort into those dangerous operations and know what they’re doing, it won’t), and so on. Communicating that in a way the business folks will care about is hard, and the full costs are difficult to account for. [edit] hell, communicating that in a way the weaker end of technical managers will care about can be hard, for that matter. If they came up “doing it wrong” and are of a certain mindset, good friggin’ luck.

archi42 7y ago

Hm, at $job we're already sending all git commits to a Bugzilla (no bug in commit comment => push is rejected). Parsing the comment or diff for these instructions shouldn't be too difficult. Though we have several products + subproducts defined in Bugzilla (that's why we can't easily migrate to more modern solutions). Not sure if there is this can be easily mapped automagically. Also, keeping track if the comment is moved around, especially if slightly altered with the same commit, might be less straight-forward. Also merges might be a pain. Could also be done for those chancy subtask/checkboxes gitlab and github offer (and which I really miss in bugzilla).

efnx 7y ago

I created srcoftruth.com for this reason, but it's a hobby project - and I'm currently rebuilding it.

caseymarquis 7y ago

Sounds pretty doable at the most basic level. Spin up a small server or use your PC, make a daemon/service which pulls your master branch in once every 15 seconds. From there you can either parse new changes on your own, or likely use hooks in git. Just parse the files for your syntax, likely using some kind of manual per page uid. From here, I would send an email into our system, as no api or credentials are needed, and we already have that set up. Using an api wouldn't be that much more work. Sounds like a fun project. The complication is that information is now in two places. So the next step is to use your tracker api to create an issue, and get the url to it. Then replace the comment in the code with the url and make an automated commit/push. Still all seems very doable and fun.

Tyr42 7y ago

Google's "infrastructure" is just people asking you to make a bug (issue) and put // TODO(b/<bug number>): Fix this up during code review. Sometimes I'll just put TODO(<username>) if I don't really care about keeping an eye on it.

gravypod 7y ago
It's too bad those tickets aren't created automatically. That probably raises the bar for people wanting to add these sorts of comments.

MAGZine 7y ago

I've already built a little tooling around pull requests and git commits at autodesk and so when I read this, I thought, oh, yeah, that's a great idea, I should do that. But here's the thing. Our team already has a policy for TODOs: either you open a ticket and leave the ticket number in the code, or you do not leave a todo at all. This way, we're never guessing which ticket belong to which todo, and all of the necessary context (including what spawned the todo, why it may or may not have been a good idea, etc) can be present with the code. I think in this case, the policy is a better system than just randomly opening tickets. It increases the barrier to entry if you are going to leave a TODO (versus leaving it out or just not being lazy and doing it), and prevents the backlog from needing even more grooming.

gravypod 7y ago
> It increases the barrier to entry if you are going to leave a TODO (versus leaving it out or just not being lazy and doing it), and prevents the backlog from needing even more grooming I would rather have many tickets that specify actual work than a lot of work specified in no tickets. Using monotony as a filter doesn't sound like it would lower defect rates over long periods of time.
- MAGZine 7y ago
  Conversely, it actually serves as a reminder for you to prioritize the work rather than coming across and old todo as a happenchance, when you're not in the frame of mind or have the time to fix it. Yes, it's tedium. But it's necessary tedium. It's documentation.

Groxx 7y ago

I've taken to adding a small linter: TODOs must have a date attached, and after that date they'll fail a (fast, skippable) lint job. My goal isn't to require tackling them, merely to make them annoying enough to prioritize. So far it has worked out pretty well - within a day or three of a deadline passing, about half the time the date gets bumped a month and a task is made for the next sprint, a third it's just fixed, and the remainder are no longer relevant so they're just deleted.

sergioisidoro 7y ago
This is a great idea. I think I might do the same. Thanks!

jpswade 7y ago

My rule is that a todo should have a way to get to done. If it’s important enough to write a todo then it’s probably worth doing and prioritising against everything else.

nightfly 7y ago
Eh, that's a bit extreme. If I write a todo in code rather than just doing it, it's because I've already made the decision that it's not important/needed enough to do now.

deleted 7y ago

[deleted]

hashhar 7y ago

RedHat has a maven plugin for this. Let me see if I can ask someone to share more details.