TODOs are a tricky subject for developers. Many codebases are guilty of having TODOs linger around while nobody knows who’s responsible for a TODO or even has the required context to tackle it. Yet, should we feel ashamed for our lingering TODOs?
Many developers have adopted the approach of adding TODOs to their project’s code. However, it’s not necessarily the best approach to manage them. It makes more sense to extract TODOs to a centralised interface that allows you to actively manage them and add metadata such as context, feature descriptions, requirements, or even relevant code snippets.
This article discusses the following questions related to TODOs:
There are different reasons why software engineers use TODOs in projects:
(Source: Todo Tree extension Visual Studio Code)
The most important problem with TODOs is their lack of context. Developers often write short TODOs that don’t give a lot of context to solve them. Therefore, TODOs are often only resolvable by a few people who have a lot of knowledge about the codebase. It’s even possible that only the engineer who wrote the TODO knows what needs to happen.
Moreover, TODOs don’t have a clear owner except for the creator of the TODO. When you encounter a TODO when working on somebody else’s code, do you remove the TODO or try to resolve it? It’s a tricky question to answer. I remember experiencing TODOs as a college’s personal note that I wasn’t allowed to touch.
Now let’s think about what happens with TODOs. How often do TODOs end up in the master/main branch without being addressed? Even months after merging the TODO into the project’s code, it remains unaddressed. It mainly occurs because of their lack of ownership and context.
Lastly, TODOs expire quickly. Code changes rapidly, especially within a large development team. This means that TODOs aren’t valid anymore or don’t make sense in the current codebase. Again, nobody dares to remove them because of their lack of context. To solve this problem, some companies use different project management and technical debt tools that let you set deadlines and add context.
These guidelines are not an exact rulebook for managing TODOs because it depends on your team’s preferences, size, and management style. Hence, here’s a list of four tips that help you to better manage your team’s TODOs.
Software engineers should only use TODOs for defining microtasks that any team member can quickly tackle. For instance, you could add a TODO to remind developers about changing the name of a module to a more descriptive name. It’s not a task that requires a separate ticket in a project management tool.
Bigger issues or tasks require the use of a project management tool. It allows you to define specifications for the issue and plan it as part of a development sprint.
Solely adding TODOs in the codebase is not the best way to raise issues with code. If you’re looking for ways to organise your issues and add context, try out Stepsize. It allows engineers to import their TODOs into the platform, to organise them and add context such as linking code, dependencies and add metrics such as hours lost.
A consistent format for your TODOs allows you to better manage them. For instance, you could opt for a format that defines a due date and an owner.
Alternatively, you could define more properties like references to code snippets or relevant files.
When you have a consistent format, it’s much easier to accept TODOs during code reviews that fit the defined format. It prevents your team from ambiguous TODOs ending up in your project. On top of that, a fixed format allows you to search TODOs in your codebase quickly.
Sit together with your team to set rules for TODOs. For instance, define for which kind of tasks you allow the usage of TODOs. By clarifying this, it’s much easier to identify a microtask versus a task that requires the assistance of a project management tool.
To add my opinion, I’m not a big fan of managing TODOs within the codebase. However, this strategy can work for smaller teams with the right set of rules. Don’t forget to provide context and identify a clear owner.