// todo 2022-06-09 something
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.
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.
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.
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.
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.
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.
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.
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.
A todo is a todo. I don't see why a date is necessary.
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.
Indeed a date in a TODO is irrelevant, and more importantly revision control systems already track the date when the TODO was added and updated.
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.
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.
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.
throw "TODO" // <comment with some additional context to remember>
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.
It's a really good read.
https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-...
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.
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
task updateTODO(type: Exec) {
commandLine "bash", "-c", "grep -ri \"\\bTODO\\b\" src > TODO"
}
- 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.
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.
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.
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.
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.
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.
Could have been a cool approach of GitHub or gitlabs issue tracker to be some sort of to-do comment tracker