We all write the dreaded // TODO: and // FIXME: comments every once in a while. Sometimes we do it because we know our code can be better but we're not sure how, other times we don't have the time to write an optimal solution because of deadlines, and other times we just want to move on to more interesting problems to solve and we just slap a // TODO: on our code and call it a day.
In today's post, I would like to give you five tips to make sure your todos eventually get fixed and don't end up haunting your code unnoticed until the end of times.
1. Sign your todos with a date and your name
The first tip is possibly the most important in my opinion. If you leave a todo in your code, sign it with your name and with the current date. This makes it really clear to you and anybody on your team how long the todo has been there for, and how who left the todo there. The purpose is not to play the blame game or to point fingers but more to ask the original todo writer if the todo is still relevant, and whether there is a Jira ticket, Trello ticket or any other kind of ticket in whatever system you use to track work that must be done.
It's also possible to extract the todo author and date from git but this can sometimes be problematic, especially if code marked with the todo is moved around, or a typo is fixed because the todo will then carry an entire history. It's much more convenient to have the basic information about the todo item available at a glance.
2. Mark your todo with #warning
If your project has very few warnings and you tend to pay attention to the warnings that Xcode shows in your project, it's a good idea to make your todos show up as compiler warnings. You can do this by writing your todos as follows:
#warning("TODO: donnywals, 2020-01-08 - Improve this algorithm, I'm sure we can get this to O(1) somehow.")
When you write your todo as a #warning rather than a comment, Xcode will treat it as a compiler warning. This makes your todos stand out even more, and when combined with tip 1 your todos will be easily visible because they show up as warnings and you have all the context you might night right there in the warning.
3. Use SwiftLint to mark todos as warnings
An alternative to using #warning is to use SwiftLint. SwiftLint is a tool that helps you and your team write nicely formatted Swift code by analyzing your code and showing compiler warnings when you violate any of its rules. SwiftLint has a rule that flags any occurrences of a // TODO comment in your as compiler warnings.
If you don't like using #warning for your todos because you prefer comments, but also want to be warned about any todos in your code then SwiftLint is the way to go.
4. Remove todos if they don't get done for a while
To avoid everlasting todo items that never get fixed, make sure to go through and clean up your todos every once in a while. If you mark your todos with an author and a date, it's easy to find out which todos have been lingering for far too long and you can quickly reach out to your teammates to find out what the status of a todo is and whether it's still relevant.
A good approach here is to set aside an hour or so every couple of weeks to go through the project I'm working on to see if there are any todos that have been around for more than a month and where I don't know what their status is. I have noticed that when a todo has been around for more than a month or two, they have often become irrelevant, or I realize that implementing the todo hasn't been prioritized yet. This often leads to the todo getting prioritized, or removing it because the todo is no longer relevant.
5. Avoid todos altogether
This one is cheating a bit, but the best way to have better todos is just to avoid them completely. Whenever you find yourself writing a todo, ask yourself why. You'll often find that the answer is that you just want to move on to the next thing or because you're not sure how to do the thing you want to do, and for some reason, you decided that you don't want to figure it out right now. In many cases, you might just as well go ahead and do what needs to be done right away and avoid writing the todo altogether.
If you're reviewing a PR from one of your teammates and you spot a todo in their code, it's absolutely okay to ask them why the todo is there and try to convince them to take care of the todo now rather than at some time in the future. If the todo is reasonable, try to find out if the todo has been added to your ticketing system to make sure the work is prioritized eventually so the todo can be marked as completed.
In summary
I hope that with this list of ways to get better at writing todo items you can improve your codebase a little bit. Todos are inevitable in most codebases, but it's important that manage them well to avoid having lots of hidden todos in your code that nobody remembers or cares about anymore.
If you have any more tips on how you handle todos in your projects, make sure to let me know!
Top comments (9)
5 all day :)
Almost the same as comments - asking yourself why you're doing this and handling it right there is definitely the say to go. If it is a task that needs to get done, I've found adding it to your backlog so there's some accountability is a better way to go.
A tip so simple yet so difficult in practice... 🤦♂️
Totally agree on being upfront on the cost associated with not paying down tech-debt, and that is a definite advantage to having TODO items as tickets -- generally speaking the biz folks aren't in the code, so they don't see TODO's, but they will see an issue in JIRA or whatever task tracker you use.
It took me an embarrassingly long time to realize it's nearly always better to "just do the thing" right then. Obvious, in retrospect...
I like the idea of filing an issue for things, but I've found in practice those issues never get done (they tend to be hard to prioritize over other biz-facing features) & tend to clutter up backlogs.
Generally speaking the size of a TODO item tends to be quite small, probably too small to be encapsulated as a single issue in a task tracker, so if every "TODO" item became an issue there's a very real risk of being killed by a thousand paper cuts" as well.
TODO's in code can have the same issue around "never getting done", but at least then while working in an area of code you're forced to see related TODO items in that area that can give you context around shortcomings or areas in which that code can/should be improved.
From my experience TODO tends to stay in the code forever. I only use them while I'm refactoring some code or if I know I'm going to deal with them within a few days to complete a feature. As a matter of fact I'm now in the midst of migrating a project from Objective-C to Swift and I'm using a lot of TODO, but I know they'll eventually go away.
The problem with TODO is sometimes you use them when you write something in a hurry, you feel is not optimised and you leave a comment for the future self to refactor that particular piece of code. You'll hardly find time to deal with it, and the TODO will stay there so just avoid adding it in the first place.
Exactly, marking your todos with your name and date helps you and your team to keep you accountable. And making sure you have a ticket in your tracking system of choice ensures that nobody forgets them. And by calling them out in a code review and asking for the todo to be resolved before merging prevents the todo from ending up in your code base completely.
I would say put a ToDo as a place holder in the code only if you create a new story/feature for the work to be planned.
otherwise they just create noise in the code
I love #5. If I see the same poor design more than once, I'll take some time to refactor. Boy Scout's Principle :)