One of my favorite small linters I made on a previous team:<p><pre><code> // todo 2022-06-09 something
</code></pre>
^ on that date, it'd fail the linter, and print the comment. Every TODO needed a date.<p>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.<p>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.
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.<p>[1] <a href="https://gist.github.com/hraban/10c7f72ba6ec55247f2d" rel="nofollow">https://gist.github.com/hraban/10c7f72ba6ec55247f2d</a>
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.
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.
Unless I've misunderstood, I don't like this proposal. To me:<p>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.<p>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.<p>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.
One trick I employ for myself is:<p><pre><code> throw "TODO" // <comment with some additional context to remember>
</code></pre>
Substitute for your language's syntax of course.<p>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.<p>The placeholders are then implicitly flagged in test runs and easily found. Basically my text search results for 'throw "TODO"' become my TODO list.
Mark Seeman wrote a book about Writing code that fits in your head.<p>It's a really good read.<p><a href="https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-your-head/" rel="nofollow">https://blog.ploeh.dk/2021/06/14/new-book-code-that-fits-in-...</a>
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.
I dislike //TODOs for the same reason I dislike commented out code.<p>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.<p>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.<p>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.
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.<p>This fits my workflow because<p>1) Github and pull requests<p>2) our normal commit messages start with an emoji (:+1: or :wrench:)<p>3) there's rarely more than 10 commits per PR so you can't miss it
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<p><pre><code> task updateTODO(type: Exec) {
commandLine "bash", "-c", "grep -ri \"\\bTODO\\b\" src > TODO"
}
</code></pre>
Advantages:<p>- It's unintrusive and the TODOs get updated automatically (Also doesn't create sudden build failures like some approaches suggested on this thread)<p>- 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.<p>- 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.
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.)
I used to create a lot of TODOs in the code to track things but some developers just do not prefer this way.<p>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.
My stack has sth like that on by default. It uses the common words: TODO, FIXME, BUG.<p>I can’t merge a pull request, if there is one new todo added.<p>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.
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.<p>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.
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?
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.
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!
I like todo comments, but I feel like they miss a dashboard.<p>Could have been a cool approach of GitHub or gitlabs issue tracker to be some sort of to-do comment tracker
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.