Today’s exercise is short and sweet: grep your codebase for TODO comments.
When you find one, I recommend you do one of the following:
Is it out of date? Delete it.
Is it still relevant? Delete it and add it to whatever system you use to track work to be done, like GitHub Issues or Trello or Asana.
Are you unsure? Do a little research and/or track down the comment’s author and get an answer. Then do 1 or 2 :).
Why do this? Because code is a lousy place to track todos. When a todo lives in your code, it can’t be prioritized or scheduled, and tends to get forgotten.
For extra points, submit a PR that deletes all the TODO comments and include links to the newly-created issue for each one. Should make for an easy review/approval.
Worth noting: spend 20 minutes on this task and then declare victory. Success is showing up and putting in the time, not necessarily deleting every comment. If you can only delete one comment in 20 minutes, you’ve still succeeded for the day (well done!)
Finally, when you’re done, please share how old the oldest TODO comment you found.
This task doesn’t go down too well at my work. A particular person likes them since we can easily find WHERE these issues should be changed, but the issue tracker should have a clearer description.
For some reason, we love adding TODO: <Issue Number> into our code base. The oldest issue I got to was Jan 2017, but I also noticed issues that had actually been completed, but the TODO comment not removed - amazing!
I’m working on a codebase that is only a few months old so thought I wouldn’t have any TODOs to cleanup but I found five of them in places I never would have thought. All of them were from the first week of development and no longer made any sense in the code so I removed them.
Being the newest member of the team yesterday was really helpful in fixing up the README, but today, I felt like I was lacking a lot of the backstory of the TODOs. Found myself going down a git blame rabbit hole to get context of when they were introduced.
Was able to remove 6! And was encouraged by the fact that the most recent TODO was 9 months ago.
Oldest was from 2013-11-26 (while the ‘initial commit’ was from 2013-05-09).
For I knew I was the only one who started adding TODO-flags in the project I was pretty surprised facing quite a lot of them.
I created issues for the topics related and deleted them in the source.
This rose a new challenge: How to deal with changes to the database-object sources if it’s only a change of comments? Deliver it to the customer via migration-files (Pro: Target database and source status are identical, Contra: Huge overhead) or only committing the changes to VCS?
I finally decided to not create migration-files for these changes because I thought the overhead and risk (which is included in every migration) outweighs the benefits of having identical source status. This is because we don’t work with schema-comparison for delivery but rely solely on scripted migrations.
Once the next meaningful change is done to the database-objects, the updated comments will be delivered as well.
I had 3 objects that had TODOs: one was mine and the other 2 were code that I got from an outside third party, so the TODO was theirs. In my case, the TODO was more of a note about the timing of processes, so the TODO was more of a comment and not an action item, so I removed the TODO part and left the comment there. That TODO would have been there since about May 2015.
I’m not having much success REMOVING the TODOS, but it’s definitely bringing me around the codebase on a tour… I just joined the team last week and the worst offender of the TODOs also happens to be their staunchest defender. I’ve already disagreed with him on more than one thing, so I’m trying to take it slow with the opinion havings.
For this one I cheated because I remember this being one of the examples @ben mentioned on the podcast and I did it back then. Still, my code gained about 10 TODOs since then. Most of these TODOs were valuable as comments in the code because they were around hacky code, code that should be removed, etc. I wanted to keep the context for whoever is reading the code, so, I added them to Jira and I added the issue number to the TODO. That way, the workflow of fixing them ca be tracked with our Kanban board but the context for someone reading the code remains intact.
The oldest TODO in my pet project was just 2015 - and am somewhat embarrassed to discover that I was the author of the most recent one. Shame, shame! In my defence, it is in a feature branch, and hasn’t been committed to master yet…
To folks using grep to look for TODOs - you may want to use the -i option for case insensitive search in order to catch all the permutations of TODO/ToDo/todo/ etc.
You can also use git pickaxe to search for commits that contained (added or removed) a TODO using something like git log -S TODO -i --reverse -p. Explanation: -S is the pickaxe, -i is case insensitive search, --reverse shows you the oldest commits first, and -p shows you the patch of each commit. Bear in mind that this shows you all of the times when a TODO was introduced or removed - so you’ll get some historical information for TODOs long since gone from the codebase.