Recently, I wrote about why I think every TODO in your source code needs a ticket (LINK).
Now that a few weeks have passed, I realize that I did not give the full picture in that article. Even if you have a TODO ticket, it does not automatically mean that it will be helpful. Here is why.
Having a TODO in code always means that someone will have to revisit that code later. In a larger software project, the only way to ensure that the TODOs will eventually get done is to have the TODO go along with a ticket in the project’s ticketing system.
This ticket ensures that someone will eventually work on the ticket, and that working on the ticket will eventually fix the TODO.
But this only works if the issue follows a few rules, which I will outline here:
First, the ticket must have a description. In many reviews, I have seen tickets for TODOs that have no description at all. It may have been clear to the developer at the time what the ticket was supposed to solve, but what about a few weeks from now? Will he or she remember? Or what if someone else needs to work on that ticket later? How will that developer know what the issue is? So the rule for a TODO ticket – as for any other ticket, really – is to have a meaningful description. Why is this issue there? What needs to be done? What should I watch out for?
This brings us to the second rule of good TODO tickets: A TODO ticket should mention that there are some TODOs in the code with the number of this ticket. A simple search for the ticket’s ID in the code will reveal all occurrences of its TODO, making it obvious which lines of code need to be adjusted. But a developer working on such a task needs to know that he needs to do this search in the first place. So this is very important information to put in the TODO ticket.
The third rule for a good TODO ticket is important in larger software projects: The issue must have all the correct metadata, showing which team the issue belongs to. The metadata ensures that it will show up in a team’s backlog. Without that metadata, it might show up in the backlog of the wrong team, or no team at all. Such a ticket will get lost in the vastness of a project’s issue system and may live a lonely life forever after. Don’t let that happen to your issue.
And the last rule, which is – I hope – obvious: An open ticket that is used as a TODO in a change to the code must not be closed or resolved yet. It must remain open for future teams to work on. As I said, this is obvious, but I have seen cases where people have tried it anyway.
For larger projects, it might be a good idea to automate these rules. I think rules three and four in particular are good candidates for automation. Such a script could search the code base. There, it could search for all TODOs with a ticket number using regular expressions. For each issue ID it finds, it can then use the ticketing system’s API to check whether the ticket exists, has the correct metadata, and has not yet been resolved. If it finds any tickets that violate these rules, it can display an error message. This automation could help prevent TODOs from getting lost and never being handled properly. I have not yet tried this method, but I can imagine it being very helpful, especially as projects get larger.
To sum up: A TODO in a software project is only handled properly if there is an associated ticket. But the ticket has to follow some rules to be really useful. Follow these rules, and you will have tickets that really help you get your TODOs under control.
I am also interested in your opinion. What are your experiences and best practices with TODOs? Leave a comment below.