11 ms·

The Code Is the To-Do List

116 points by gary_bernhardt 4y ago

bakul 4y ago
May be combine this idea with Knuth’s Literate Programming? Then when you get around actually working on the task it already tells you what you’re supposed to do!
Groxx 4y ago
One of my favorite small linters I made on a previous team: // todo 2022-06-09 something ^ on that date, it'd fail the linter, and print the comment. Every TODO needed a date. Got a failure and need to get past it for now? No problem: bump the date for a week or something. Now at least two people are aware that it exists (author+reviewer)... and one is in the git history for that line. Makes it rather easy to trace back who wrote a TODO / who put it off / etc. Though we fairly quickly started adding usernames to the comments for who-to-contact. Sometimes they're just stuff to do "soon", sometimes they're no longer necessary, there are lot of reasons to delay or delete todos. But oh boy did it work. We resolved or removed about 90% of them in 2 months, and the remaining ones quickly got tasks attached and had bigger plans built around them.
- suby 4y ago
  I'm going to give this a try. Thanks for throwing the idea out there!
  - Groxx 4y ago
    We did eventually add a way to skip it outright per commit fwiw, to avoid merge conflicts when there were a lot of changes flying simultaneously. That may be worth planning on to some degree :) or show a warning if it's within a week or something. I'll also recommend generally treating it lightheartedly - the person who it interrupts is not usually the person best suited for tackling it. A no-questions-asked "you can always push the date off a bit" policy helped - poke the author of the cryptic comment so they know, and that's the end of the immediate responsibility. Target just enough friction and shared face-palming at forgetting so you don't ignore it outright, like often happens with merely printed lints, but if it becomes annoying it'll be avoided and then it's just yet another Jira competitor.
- giancarlostoro 4y ago
  How do I get such a linter into Visual Studio, I've never added anything like that to C#, my personal strategy is to just make tickets, but also with stuff like JetBrains different IDEs you can fetch all the TODO's in a list. I opt for tickets so they dont get lost.
  - briHass 4y ago
    VS automatically creates a To Do list window with all your TODO and similar comments. If you don't want to go as far as making it a git hook or built into your CI, you can use something like this: https://marketplace.visualstudio.com/items?itemName=MattLaceyLtd.WarnAboutTODOs https://marketplace.visualstudio.com/items?itemName=MattLace...
- agumonkey 4y ago
  nice trick, placing scheduling in code seems interesting
- yakshaving_jgt 4y ago
  I had a similar idea a few years ago, but with a git hook. https://jezenthomas.com/using-git-to-manage-todos/ https://jezenthomas.com/using-git-to-manage-todos/
  - Groxx 4y ago
    Yeah, a lightly-annoying-when-passed hook would probably be a better fit for smaller environments / personal use. I may have to set that up for my own stuff, thanks! I set mine up in our CI environment because it was essentially trivial to do so, and it also caught people who didn't have hooks installed... but that's only really relevant because we had a couple dozen engineers rotating between many other projects that religiously avoid hooks. It was far too likely to be forgotten unless it was automated.
- shikoba 4y ago
  > Every TODO needed a date A todo is a todo. I don't see why a date is necessary.
  - Groxx 4y ago
    It was just to ensure it wasn't forgotten. If it's "long term", stick it for a year out or something, it's fine. Truly timeless? Year 2999 works pretty well, or just don't use "todo" because it apparently isn't gonna happen. We fairly often used it for stuff like "X should be upgraded to fix Y by now, see if this hack is still necessary". If was not, just push it out and check again then. Or do whatever else might be necessary since it didn't meet expectations. I've encountered many codebases with todos that are years old, sometimes authored by people no longer at the company. A date ensures these aren't lost forever. You can always just push it another year out.
    - shikoba 4y ago
      You can grep for todo in your codebase. It will list them.
    - arinlen 4y ago
      > It was just to ensure it wasn't forgotten. Why don't you just add a ticket in a ticket backlog, then?
      - ParetoOptimal 4y ago
        Most of the time it's not possible to trust items you add to the backlog related to tech debt will actually get done. Why make lists that will never be completed? Or put another way, there is no pain that can't be avoided by ignoring the backlog. You can only ignore these TODOs until your build fails, then you have to reflect on whether to do them, push them into the future, or delete them. I think this works because it really makes backlog grooming a group activity where everyone is involved, so everyone feels they have a say in setting priority.
    - marcosdumay 4y ago
- vages 4y ago
  My team also dates its todo items by the date of creation. I have played with the idea of failing building or linting after a specific date, but I have said no. I want to be able to check out a specific commit and have the same experience as when the commit was created. Having the linter fail based on the current computer clock setting would make that impossible.
  - Groxx 4y ago
    Definitely agreed, don't tie linting like this to your build system. It'll also suck if it blocks fixing an urgent problem.
- singularity2001 4y ago
  isn't tracking date and username provided by git (blame)?
  - Groxx 4y ago
    The authoring date is, yes. But not the "remind me at" date. As for author: yes definitely. And it's a great fallback option. But it's not visible in most code review UIs, and even when it is it tends to be the most recent editor, not the author. Git's CLI makes the full history of a line pretty easy to read with -L (usually, depending on if it detects a move or not), but have you ever tried to do that on GitHub? Back through several versions? It's a freaking nightmare, and nobody will try to do that while reading a diff.
- arinlen 4y ago
  > Got a failure and need to get past it for now? No problem: bump the date for a week or something. Now at least two people are aware that it exists (author+reviewer)... and one is in the git history for that line. That sounds like an awful strategy, one that needlessly creates problems and revision history noise and team distractions. Is it awful if a comment leads your CICD pipeline to break? Now imagine having your CICD pipeline break because of a TODO item. Just create a ticket in your ticket queue and get rid of that TODO.
  - bottled_poe 4y ago
    You could have the best of both worlds by making the CI job search the backlog for overdue critical tasks.
  - srer 4y ago
    I do that, create the ticket. I want to believe it means one day we will do that TODO, it'll beat the priority of all the other tickets in the queue. But it never does, there's always some critical new feature sales wants, or something bigger on fire. I still create the tickets, as a kind of cathartic process, a confession to the jira gods, I have sinned and half assed something. Please take this ticket as my penance.
    - actionfromafar 4y ago
      In Eastern Liturgy, the ticket is the confession and the mandated overtime is the penance.
    - KronisLV 4y ago
      > But it never does, there's always some critical new feature sales wants, or something bigger on fire. Then clearly it is not deserving of your attention according to the powers that be. If it is, then talk in the language that these parties understand better/prefer: bump up the priority of the task, add a "blocked by" or "has to be done after" link to these other issues in the tracker and tell the rest of the teammates that you'll be working on that piece of technical debt instead of the new feature. If you can't do that, then either the "TODO" comments/issues aren't important enough, or they're not deemed to be and will/should simply be left to rot until you either have an abundance of time to address them (which may be never), or the project is retired. If more pushback is necessary, then do it doing any estimates (provided that you have any): "Task $FOO will take X% more time due to $BAR not being finished and slowing down development. Consider doing $BAR first and $FOO should become less complex then."
- jillesvangurp 4y ago
  It would be a cool little side project to automatically track TODO's and FIXMEs with an issue tracker. There is a lot of monkey work involved with issue tracking currently and a lot of work that isn't tracked or poorly tracked because of it. Lowering the barrier to make work and tasks more visible is useful.
  - FooBarBizBazz 4y ago
    Jira creates so much friction. It's a trillion dollar drag on the Tech industry. It should be as quick as writing a Slack message.
- quickthrower2 4y ago
  Even better: do it now, or not at all. If it is a failing test do it now anyway. The reason is the person adding the TODO may have a bias that their thing really is the most important tech debt. However I would step back and figure out what tech debt payback offers the best ROI with the team. If you have a pet hate refactor you want done, add it to a personal list and bring it up for consideration in that process. Or just fix it as part of your task if practical to do so.
- planede 4y ago
  I don't get why so many people likes this. No, I don't want a suddenly failing pipeline on master because of an expiring TODO. A better approach is for a TODO to be required to reference a ticket, and add a ticket. Prioritization should happen in your issue tracking, not in the code.
  - ParetoOptimal 4y ago
    Because the annoyance means it will get fixed? In issue tracking it just gets archived.
    - planede 4y ago
      If you want to set it a date, then set a deadline for the issue. It should still annoy the right person.
    - arinlen 4y ago
      > Because the annoyance means it will get fixed? In issue tracking it just gets archived. That makes no sense at all. If a ticket is archived them that means the issue was evaluated and considered irrelevant and a distraction that should be ignored. Otherwise in the very least it should be placed on a backlog, and reconsidered each and every single time someone picks/is assigned a new task. Nagging through out-of-band means to push an irrelevant task that was already considered and discarded makes all matters worse, and frankly sounds like a playground for petty passive-aggressive office politics.
  - jandrewrogers 4y ago
    Many TODOs (the majority in code bases I've worked on that had them) do not require any action, they are annotations to the code base about future potential development or research. Addressing the TODO, either by removal or implementation, could be deferred indefinitely with no consequences and often are. These aren't things that need to be fixed per se. For example, I've seen TODOs widely used to document optimization or generalization opportunities in the code base. You do not want to pollute your ticketing system with myriad TODOs. They are not meaningfully actionable and they tend to require very local code context so it is easier to understand them as code annotations.
SenHeng 4y ago
I have another method where I simply create a commit with nothing but the TODO/FIXME/DELETEME comments where the commit message is same content. I then make sure to delete all of those commits later before creating a pull request. If I forget any of it, it's obvious just by looking at the list of commits. This fits my workflow because 1) Github and pull requests 2) our normal commit messages start with an emoji (:+1: or :wrench:) 3) there's rarely more than 10 commits per PR so you can't miss it
hboon 4y ago
I write a whole bunch of //hhh and //hhh1 (and so on) comments for myself and have a pre-commit hook to scan for them.
noufalibrahim 4y ago
I had a different approach but only for personal projects. I used Emacs org-capture to do this as a ToDo. It would remember the file, line and I could schedule a date for it. I used to plan my days using org-agenda and the TODO would show up as a task for the date on which I scheduled it. It would also gather information from emails and other things so on the overall, it was a workable system. No syncing to the outside world and stuff like that though. Also, not very usable in a collaborative environment. Worked very well for personal projects though.
adamddev1 4y ago
This is a great idea. But I would like my eslint to produce a WARNING, not an ERROR when I have a certain keyword in a comment. Like if I wrote FIXME in a comment I would like it to produce and eslint warning which would let the code compile and reload (in create-react-app let's say) but it wouldn't build in CI because it has a warning. Is there a way to do this with eslint?
- tw102 4y ago
  This is exactly what the article describes. Lint ERRORs that block CI but not compilation.
  - adamddev1 4y ago
    No unfortunately for me using create-react-app an ERROR like this article's config produces blocks compilation as well. I would need it to output a WARNING for compilation to continue but I can't see how to do that with no-warning-comments
unnouinceput 4y ago
I'm pretty sure "XXX" in their case was chosen exactly because of the more general meaning. I'd sit on a bunch of their code reviews meetings, I bet they have a lot of fun when one of those TODO's pop-up.
lupin_sansei 4y ago
The beauty of this idea is that it solves the usual to-do list problem of adding a task and then ignoring it forever.
QuadrupleA 4y ago
Nice article and idea. I've used TBD comments for years but it was always up to me to informally circle back later and deal with them. An automated commit/merge-stopper seems like a good way to approach it. The observations about maintaining the context of what you're working on in your short-term memory, and how much faster you can do things that require it while you have it are very true.
danielovichdk 4y ago
Mark Seeman wrote a book about Writing code that fits in your head. It's a really good read. https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-your-head/ https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-...
wodenokoto 4y ago
I like todo comments, but I feel like they miss a dashboard. Could have been a cool approach of GitHub or gitlabs issue tracker to be some sort of to-do comment tracker
furyofantares 4y ago
I just put //TODO:<my initials> and don't see a linter for it adding anything really. I don't think I've ever checked in that way, because I read all my code right before I check in, but maybe this is a difference in workflow (I've mostly used p4; I can see a git workflow that involves lots of local commits being different.)
yuvalr1 4y ago
I always use code comments with my name during the work to help me remember things I want to change but don't want to do them right in this moment. Then before pushing I make sure there is no comment bearing my name.
- 100011_100001 4y ago
  I use // FIXME for the same reason. When I get ready to create my merge request a global // FIXME will point out anything I missed.
Elte 4y ago
Along these lines, I find a "nocommit" git hook [1] to be an absolute life saver. If for whatever reason I need to temporarily break a piece of code, I just add a `// NOCOMMIT` comment above it, and git won't let me commit if I forget to change it back. [1] https://gist.github.com/hraban/10c7f72ba6ec55247f2d https://gist.github.com/hraban/10c7f72ba6ec55247f2d
erung88 4y ago
I used to create a lot of TODOs in the code to track things but some developers just do not prefer this way. My team later switches to more formal project management tools to keep track of TODOs and other tasks (e.g. follow up with clients, etc) and this seems to work better for us.
- arinlen 4y ago
  > I used to create a lot of TODOs in the code to track things but some developers just do not prefer this way. Requiring TODO items to be created and tracked in an issue tracking system instead of sprinkling comments in source code is a no-brainer, quite honestly. Issue/bug tracking systems were explicitly created to help teams track pending work. It makes no sense at all to misuse code comments to do the exact same job that's already done by any ticketing system. Complaining that TODO/FIXIT comments are forgotten when any team workflow is based on constantly reviewing pending tickets and assigning them to team members is something that's hard, if not outright impossible, to justify.
andix 4y ago
My stack has sth like that on by default. It uses the common words: TODO, FIXME, BUG. I can’t merge a pull request, if there is one new todo added. And also my IDE (jetbrains) shows me a warning, when I want to commit/push code with new todos. And it has a tool window that lists them.
edvald 4y ago
One trick I employ for myself is: throw "TODO" // <comment with some additional context to remember> Substitute for your language's syntax of course. I find this especially handy when writing test specs, but it's also handy when creating new functions etc. For tests I lay out the test descriptions with just this one line in the function body. For new functions/methods I can define the function and its return type (assuming a type-safe language) which makes the code using it compile, but leaves the implementation TBD. The placeholders are then implicitly flagged in test runs and easily found. Basically my text search results for 'throw "TODO"' become my TODO list.
- quickthrower2 4y ago
  That sounds good within a feature branch but you wouldn’t merge those to main, right?
  - Groxx 4y ago
    to be fair, that is what the linked post is talking about :) so super-explicitly breaking things serves pretty much the same purpose, as long as you have attentive reviewers and/or tests that touch that code.
  - edvald 4y ago
    No definitely not, this is just for WIP branches. I usually don’t even push these, unless it’s something big that I need early review on.
lbriner 4y ago
Unless I've misunderstood, I don't like this proposal. To me: Scenario 1: The code needs doing as part of the work I am doing. Solution: Do it before your current branch is merged otherwise your story is not complete. Scenario 2: The code will eventually need doing but not now. Raise a task/ticket. Don't pollute the code with things that might never get done. We intended to remove a load of old code previously and haven't done it in 2 years because it isn't a problem. I don't understand why you want to carry on working but hold back the entire codebase until the second piece of work is done.
- jeremyjh 4y ago
  As I understand it, this is a forced reminder for scenario 1; to ensure the other change is also made before merge.
sethammons 4y ago
In code review, I ask that any TODO be augmented with a link to the jira ticket tracking it. If it is not in jira, it is not getting priority. If it is too small to justify a ticket, fix it then and there.
100011_100001 4y ago
I dislike //TODOs for the same reason I dislike commented out code. It adds noise to the code with no actual benefit. If a TODO is outdated it actually becomes a false flag, it's like a comment that doesn't reflect the code changes so now it adds to the confusion instead of alleviate it. Personally I add // FIXME while writing code but I make sure to remove all of them prior to creating a merge request. It's my way to track outlier issues that I will turn around and fix as I parse my code. If I find a // FIXME that deserves to be its own enhancement or a future TODO I will capture it as a story. My org is Agile story driven which is why I put it there. Perhaps adding TODOs for a personal project is fine. However for repositories that multiple developers touch a TODO at best is noise, at worst a point of confusion.
madmax108 4y ago
I've had great success with a lot of smaller engineering teams (3-8 Engineers) just using a simple grep of codebase to write out TODOs to a seperate file at root directory of the and make this part of the build process. eg task updateTODO(type: Exec) { commandLine "bash", "-c", "grep -ri \"\\bTODO\\b\" src > TODO" } Advantages: - It's unintrusive and the TODOs get updated automatically (Also doesn't create sudden build failures like some approaches suggested on this thread) - It's in the git repo so accessible to everyone easily and you don't need any special tools/plugins to see TODOs. Even better, I can just give a link (since it's just a github link) to the TODOs file to someone like a PM/PO to get time for my team for engineering tasks without needing to go through creating tickets and "BaCkLoG GrOOmINg" stuff. - Every few months, we organize a refactoring sprint where having all TODOs in a single place allows engineering team to sit together and see what the TODOs are that need to be handled.
IceMetalPunk 4y ago
I use FIXME comments for this, though my team's project doesn't have esLint set up to error on them, and I don't think the rest of the team would be good with modifying the esLint settings we've used for so long. But I have the TODO Tree extension for VSCode, so I can quickly jump to any FIXME comments when I need to go back to do stuff, and I don't open any PRs until there are no FIXME's left, so it's a self-enforced version of what the blog mentions.
blumomo 4y ago
How could such a linter rule be enforced with python? does such a linter rule exist here, too?
- wutbrodo 4y ago
  This technique is pretty trivial, and thus very generalizable. When I was at Google as a new grad, I used to put comments with the wrong number of slashes for my internal todos, which would cause the regular linter to pick it up before review. You can piggyback on any such linter rule very easily.
  - mattnewton 4y ago
    My usual was DO NOT SUBMIT which would show up in all red in the editors and code review tools after the woodly-doodly incident (someone changed WD to woodly doodly to test they were seeing their code and accidentally shipped it). It’s easy to teach your tools about a magic phrase like this

May be combine this idea with Knuth’s Literate Programming? Then when you get around actually working on the task it already tells you what you’re supposed to do!

Groxx 4y ago

One of my favorite small linters I made on a previous team: // todo 2022-06-09 something ^ on that date, it'd fail the linter, and print the comment. Every TODO needed a date. Got a failure and need to get past it for now? No problem: bump the date for a week or something. Now at least two people are aware that it exists (author+reviewer)... and one is in the git history for that line. Makes it rather easy to trace back who wrote a TODO / who put it off / etc. Though we fairly quickly started adding usernames to the comments for who-to-contact. Sometimes they're just stuff to do "soon", sometimes they're no longer necessary, there are lot of reasons to delay or delete todos. But oh boy did it work. We resolved or removed about 90% of them in 2 months, and the remaining ones quickly got tasks attached and had bigger plans built around them.

suby 4y ago
I'm going to give this a try. Thanks for throwing the idea out there!
- Groxx 4y ago
  We did eventually add a way to skip it outright per commit fwiw, to avoid merge conflicts when there were a lot of changes flying simultaneously. That may be worth planning on to some degree :) or show a warning if it's within a week or something. I'll also recommend generally treating it lightheartedly - the person who it interrupts is not usually the person best suited for tackling it. A no-questions-asked "you can always push the date off a bit" policy helped - poke the author of the cryptic comment so they know, and that's the end of the immediate responsibility. Target just enough friction and shared face-palming at forgetting so you don't ignore it outright, like often happens with merely printed lints, but if it becomes annoying it'll be avoided and then it's just yet another Jira competitor.
giancarlostoro 4y ago
How do I get such a linter into Visual Studio, I've never added anything like that to C#, my personal strategy is to just make tickets, but also with stuff like JetBrains different IDEs you can fetch all the TODO's in a list. I opt for tickets so they dont get lost.
- briHass 4y ago
  VS automatically creates a To Do list window with all your TODO and similar comments. If you don't want to go as far as making it a git hook or built into your CI, you can use something like this: https://marketplace.visualstudio.com/items?itemName=MattLaceyLtd.WarnAboutTODOs https://marketplace.visualstudio.com/items?itemName=MattLace...
agumonkey 4y ago
nice trick, placing scheduling in code seems interesting
yakshaving_jgt 4y ago
I had a similar idea a few years ago, but with a git hook. https://jezenthomas.com/using-git-to-manage-todos/ https://jezenthomas.com/using-git-to-manage-todos/
- Groxx 4y ago
  Yeah, a lightly-annoying-when-passed hook would probably be a better fit for smaller environments / personal use. I may have to set that up for my own stuff, thanks! I set mine up in our CI environment because it was essentially trivial to do so, and it also caught people who didn't have hooks installed... but that's only really relevant because we had a couple dozen engineers rotating between many other projects that religiously avoid hooks. It was far too likely to be forgotten unless it was automated.
shikoba 4y ago
> Every TODO needed a date A todo is a todo. I don't see why a date is necessary.
- Groxx 4y ago
  It was just to ensure it wasn't forgotten. If it's "long term", stick it for a year out or something, it's fine. Truly timeless? Year 2999 works pretty well, or just don't use "todo" because it apparently isn't gonna happen. We fairly often used it for stuff like "X should be upgraded to fix Y by now, see if this hack is still necessary". If was not, just push it out and check again then. Or do whatever else might be necessary since it didn't meet expectations. I've encountered many codebases with todos that are years old, sometimes authored by people no longer at the company. A date ensures these aren't lost forever. You can always just push it another year out.
  - shikoba 4y ago
    You can grep for todo in your codebase. It will list them.
  - arinlen 4y ago
    > It was just to ensure it wasn't forgotten. Why don't you just add a ticket in a ticket backlog, then?
    - ParetoOptimal 4y ago
      Most of the time it's not possible to trust items you add to the backlog related to tech debt will actually get done. Why make lists that will never be completed? Or put another way, there is no pain that can't be avoided by ignoring the backlog. You can only ignore these TODOs until your build fails, then you have to reflect on whether to do them, push them into the future, or delete them. I think this works because it really makes backlog grooming a group activity where everyone is involved, so everyone feels they have a say in setting priority.
  - marcosdumay 4y ago
vages 4y ago
My team also dates its todo items by the date of creation. I have played with the idea of failing building or linting after a specific date, but I have said no. I want to be able to check out a specific commit and have the same experience as when the commit was created. Having the linter fail based on the current computer clock setting would make that impossible.
- Groxx 4y ago
  Definitely agreed, don't tie linting like this to your build system. It'll also suck if it blocks fixing an urgent problem.
singularity2001 4y ago
isn't tracking date and username provided by git (blame)?
- Groxx 4y ago
  The authoring date is, yes. But not the "remind me at" date. As for author: yes definitely. And it's a great fallback option. But it's not visible in most code review UIs, and even when it is it tends to be the most recent editor, not the author. Git's CLI makes the full history of a line pretty easy to read with -L (usually, depending on if it detects a move or not), but have you ever tried to do that on GitHub? Back through several versions? It's a freaking nightmare, and nobody will try to do that while reading a diff.
arinlen 4y ago
> Got a failure and need to get past it for now? No problem: bump the date for a week or something. Now at least two people are aware that it exists (author+reviewer)... and one is in the git history for that line. That sounds like an awful strategy, one that needlessly creates problems and revision history noise and team distractions. Is it awful if a comment leads your CICD pipeline to break? Now imagine having your CICD pipeline break because of a TODO item. Just create a ticket in your ticket queue and get rid of that TODO.
- bottled_poe 4y ago
  You could have the best of both worlds by making the CI job search the backlog for overdue critical tasks.
- srer 4y ago
  I do that, create the ticket. I want to believe it means one day we will do that TODO, it'll beat the priority of all the other tickets in the queue. But it never does, there's always some critical new feature sales wants, or something bigger on fire. I still create the tickets, as a kind of cathartic process, a confession to the jira gods, I have sinned and half assed something. Please take this ticket as my penance.
  - actionfromafar 4y ago
    In Eastern Liturgy, the ticket is the confession and the mandated overtime is the penance.
  - KronisLV 4y ago
    > But it never does, there's always some critical new feature sales wants, or something bigger on fire. Then clearly it is not deserving of your attention according to the powers that be. If it is, then talk in the language that these parties understand better/prefer: bump up the priority of the task, add a "blocked by" or "has to be done after" link to these other issues in the tracker and tell the rest of the teammates that you'll be working on that piece of technical debt instead of the new feature. If you can't do that, then either the "TODO" comments/issues aren't important enough, or they're not deemed to be and will/should simply be left to rot until you either have an abundance of time to address them (which may be never), or the project is retired. If more pushback is necessary, then do it doing any estimates (provided that you have any): "Task $FOO will take X% more time due to $BAR not being finished and slowing down development. Consider doing $BAR first and $FOO should become less complex then."
jillesvangurp 4y ago
It would be a cool little side project to automatically track TODO's and FIXMEs with an issue tracker. There is a lot of monkey work involved with issue tracking currently and a lot of work that isn't tracked or poorly tracked because of it. Lowering the barrier to make work and tasks more visible is useful.
- FooBarBizBazz 4y ago
  Jira creates so much friction. It's a trillion dollar drag on the Tech industry. It should be as quick as writing a Slack message.
quickthrower2 4y ago
Even better: do it now, or not at all. If it is a failing test do it now anyway. The reason is the person adding the TODO may have a bias that their thing really is the most important tech debt. However I would step back and figure out what tech debt payback offers the best ROI with the team. If you have a pet hate refactor you want done, add it to a personal list and bring it up for consideration in that process. Or just fix it as part of your task if practical to do so.
planede 4y ago
I don't get why so many people likes this. No, I don't want a suddenly failing pipeline on master because of an expiring TODO. A better approach is for a TODO to be required to reference a ticket, and add a ticket. Prioritization should happen in your issue tracking, not in the code.
- ParetoOptimal 4y ago
  Because the annoyance means it will get fixed? In issue tracking it just gets archived.
  - planede 4y ago
    If you want to set it a date, then set a deadline for the issue. It should still annoy the right person.
  - arinlen 4y ago
    > Because the annoyance means it will get fixed? In issue tracking it just gets archived. That makes no sense at all. If a ticket is archived them that means the issue was evaluated and considered irrelevant and a distraction that should be ignored. Otherwise in the very least it should be placed on a backlog, and reconsidered each and every single time someone picks/is assigned a new task. Nagging through out-of-band means to push an irrelevant task that was already considered and discarded makes all matters worse, and frankly sounds like a playground for petty passive-aggressive office politics.
- jandrewrogers 4y ago
  Many TODOs (the majority in code bases I've worked on that had them) do not require any action, they are annotations to the code base about future potential development or research. Addressing the TODO, either by removal or implementation, could be deferred indefinitely with no consequences and often are. These aren't things that need to be fixed per se. For example, I've seen TODOs widely used to document optimization or generalization opportunities in the code base. You do not want to pollute your ticketing system with myriad TODOs. They are not meaningfully actionable and they tend to require very local code context so it is easier to understand them as code annotations.

SenHeng 4y ago

I have another method where I simply create a commit with nothing but the TODO/FIXME/DELETEME comments where the commit message is same content. I then make sure to delete all of those commits later before creating a pull request. If I forget any of it, it's obvious just by looking at the list of commits. This fits my workflow because 1) Github and pull requests 2) our normal commit messages start with an emoji (:+1: or :wrench:) 3) there's rarely more than 10 commits per PR so you can't miss it

hboon 4y ago

I write a whole bunch of //hhh and //hhh1 (and so on) comments for myself and have a pre-commit hook to scan for them.

noufalibrahim 4y ago

I had a different approach but only for personal projects. I used Emacs org-capture to do this as a ToDo. It would remember the file, line and I could schedule a date for it. I used to plan my days using org-agenda and the TODO would show up as a task for the date on which I scheduled it. It would also gather information from emails and other things so on the overall, it was a workable system. No syncing to the outside world and stuff like that though. Also, not very usable in a collaborative environment. Worked very well for personal projects though.

adamddev1 4y ago

This is a great idea. But I would like my eslint to produce a WARNING, not an ERROR when I have a certain keyword in a comment. Like if I wrote FIXME in a comment I would like it to produce and eslint warning which would let the code compile and reload (in create-react-app let's say) but it wouldn't build in CI because it has a warning. Is there a way to do this with eslint?

tw102 4y ago
This is exactly what the article describes. Lint ERRORs that block CI but not compilation.
- adamddev1 4y ago
  No unfortunately for me using create-react-app an ERROR like this article's config produces blocks compilation as well. I would need it to output a WARNING for compilation to continue but I can't see how to do that with no-warning-comments

unnouinceput 4y ago

I'm pretty sure "XXX" in their case was chosen exactly because of the more general meaning. I'd sit on a bunch of their code reviews meetings, I bet they have a lot of fun when one of those TODO's pop-up.

lupin_sansei 4y ago

The beauty of this idea is that it solves the usual to-do list problem of adding a task and then ignoring it forever.

QuadrupleA 4y ago

Nice article and idea. I've used TBD comments for years but it was always up to me to informally circle back later and deal with them. An automated commit/merge-stopper seems like a good way to approach it. The observations about maintaining the context of what you're working on in your short-term memory, and how much faster you can do things that require it while you have it are very true.

danielovichdk 4y ago

Mark Seeman wrote a book about Writing code that fits in your head. It's a really good read. https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-your-head/ https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-...

wodenokoto 4y ago

I like todo comments, but I feel like they miss a dashboard. Could have been a cool approach of GitHub or gitlabs issue tracker to be some sort of to-do comment tracker

furyofantares 4y ago

I just put //TODO:<my initials> and don't see a linter for it adding anything really. I don't think I've ever checked in that way, because I read all my code right before I check in, but maybe this is a difference in workflow (I've mostly used p4; I can see a git workflow that involves lots of local commits being different.)

yuvalr1 4y ago

I always use code comments with my name during the work to help me remember things I want to change but don't want to do them right in this moment. Then before pushing I make sure there is no comment bearing my name.

100011_100001 4y ago
I use // FIXME for the same reason. When I get ready to create my merge request a global // FIXME will point out anything I missed.

Elte 4y ago

Along these lines, I find a "nocommit" git hook [1] to be an absolute life saver. If for whatever reason I need to temporarily break a piece of code, I just add a `// NOCOMMIT` comment above it, and git won't let me commit if I forget to change it back. [1] https://gist.github.com/hraban/10c7f72ba6ec55247f2d https://gist.github.com/hraban/10c7f72ba6ec55247f2d

erung88 4y ago

I used to create a lot of TODOs in the code to track things but some developers just do not prefer this way. My team later switches to more formal project management tools to keep track of TODOs and other tasks (e.g. follow up with clients, etc) and this seems to work better for us.

arinlen 4y ago
> I used to create a lot of TODOs in the code to track things but some developers just do not prefer this way. Requiring TODO items to be created and tracked in an issue tracking system instead of sprinkling comments in source code is a no-brainer, quite honestly. Issue/bug tracking systems were explicitly created to help teams track pending work. It makes no sense at all to misuse code comments to do the exact same job that's already done by any ticketing system. Complaining that TODO/FIXIT comments are forgotten when any team workflow is based on constantly reviewing pending tickets and assigning them to team members is something that's hard, if not outright impossible, to justify.

andix 4y ago

My stack has sth like that on by default. It uses the common words: TODO, FIXME, BUG. I can’t merge a pull request, if there is one new todo added. And also my IDE (jetbrains) shows me a warning, when I want to commit/push code with new todos. And it has a tool window that lists them.

edvald 4y ago

One trick I employ for myself is: throw "TODO" // <comment with some additional context to remember> Substitute for your language's syntax of course. I find this especially handy when writing test specs, but it's also handy when creating new functions etc. For tests I lay out the test descriptions with just this one line in the function body. For new functions/methods I can define the function and its return type (assuming a type-safe language) which makes the code using it compile, but leaves the implementation TBD. The placeholders are then implicitly flagged in test runs and easily found. Basically my text search results for 'throw "TODO"' become my TODO list.

quickthrower2 4y ago
That sounds good within a feature branch but you wouldn’t merge those to main, right?
- Groxx 4y ago
  to be fair, that is what the linked post is talking about :) so super-explicitly breaking things serves pretty much the same purpose, as long as you have attentive reviewers and/or tests that touch that code.
- edvald 4y ago
  No definitely not, this is just for WIP branches. I usually don’t even push these, unless it’s something big that I need early review on.

lbriner 4y ago

Unless I've misunderstood, I don't like this proposal. To me: Scenario 1: The code needs doing as part of the work I am doing. Solution: Do it before your current branch is merged otherwise your story is not complete. Scenario 2: The code will eventually need doing but not now. Raise a task/ticket. Don't pollute the code with things that might never get done. We intended to remove a load of old code previously and haven't done it in 2 years because it isn't a problem. I don't understand why you want to carry on working but hold back the entire codebase until the second piece of work is done.

jeremyjh 4y ago
As I understand it, this is a forced reminder for scenario 1; to ensure the other change is also made before merge.

sethammons 4y ago

In code review, I ask that any TODO be augmented with a link to the jira ticket tracking it. If it is not in jira, it is not getting priority. If it is too small to justify a ticket, fix it then and there.

100011_100001 4y ago

I dislike //TODOs for the same reason I dislike commented out code. It adds noise to the code with no actual benefit. If a TODO is outdated it actually becomes a false flag, it's like a comment that doesn't reflect the code changes so now it adds to the confusion instead of alleviate it. Personally I add // FIXME while writing code but I make sure to remove all of them prior to creating a merge request. It's my way to track outlier issues that I will turn around and fix as I parse my code. If I find a // FIXME that deserves to be its own enhancement or a future TODO I will capture it as a story. My org is Agile story driven which is why I put it there. Perhaps adding TODOs for a personal project is fine. However for repositories that multiple developers touch a TODO at best is noise, at worst a point of confusion.

madmax108 4y ago

I've had great success with a lot of smaller engineering teams (3-8 Engineers) just using a simple grep of codebase to write out TODOs to a seperate file at root directory of the and make this part of the build process. eg task updateTODO(type: Exec) { commandLine "bash", "-c", "grep -ri \"\\bTODO\\b\" src > TODO" } Advantages: - It's unintrusive and the TODOs get updated automatically (Also doesn't create sudden build failures like some approaches suggested on this thread) - It's in the git repo so accessible to everyone easily and you don't need any special tools/plugins to see TODOs. Even better, I can just give a link (since it's just a github link) to the TODOs file to someone like a PM/PO to get time for my team for engineering tasks without needing to go through creating tickets and "BaCkLoG GrOOmINg" stuff. - Every few months, we organize a refactoring sprint where having all TODOs in a single place allows engineering team to sit together and see what the TODOs are that need to be handled.

IceMetalPunk 4y ago

I use FIXME comments for this, though my team's project doesn't have esLint set up to error on them, and I don't think the rest of the team would be good with modifying the esLint settings we've used for so long. But I have the TODO Tree extension for VSCode, so I can quickly jump to any FIXME comments when I need to go back to do stuff, and I don't open any PRs until there are no FIXME's left, so it's a self-enforced version of what the blog mentions.

blumomo 4y ago

How could such a linter rule be enforced with python? does such a linter rule exist here, too?

wutbrodo 4y ago
This technique is pretty trivial, and thus very generalizable. When I was at Google as a new grad, I used to put comments with the wrong number of slashes for my internal todos, which would cause the regular linter to pick it up before review. You can piggyback on any such linter rule very easily.
- mattnewton 4y ago
  My usual was DO NOT SUBMIT which would show up in all red in the editors and code review tools after the woodly-doodly incident (someone changed WD to woodly doodly to test they were seeing their code and accidentally shipped it). It’s easy to teach your tools about a magic phrase like this