Five tips to write better todos in Xcode

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!