4 Ways You Can Organise Your TODOs as a Software Engineer

TODOs are a tricky subject for developers. Many codebases are guilty of having TODOs linger around while nobody knows whos 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 projects code. However, its 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:

• What are the different reasons software engineers use TODOs?
• What are the problems with adding TODOs to your codebase?
• What are the best practices for managing TODOs?
• Whats the best way to manage TODOs?
• Why Developers Use TODOs

There are different reasons why software engineers use TODOs in projects:

• Reminder: Imagine you are developing a new feature, and you come across a snippet of code that needs refactoring. However, the refactoring doesnt affect the new feature directly so you note it to remind yourself. Its a great example of quickly noting down a small action as a TODO that needs to be performed at a later point in time. On the other hand, the developer thinks its too much overhead to create a new issue or task in a project management tool like JIRA or Asana.

• TODOs replace a project management tool: Ive been guilty of this myself. I want to avoid setting up a project board for small projects because it feels like a waste of time. For that reason, many developers add dozens of TODOs to their projects code to replace the need for a project management tool.

• Keep pull requests small: Some developers prefer small pull requests because they are easier to review. Therefore, they create multiple smaller PRs to tackle a single task. To keep track of the work that needs to be done as part of this task, they include TODOs to their PRs to remind themselves of unfinished work.

• Tips: Developers often abuse TODOs as tips for the next developer working on the same code. A TODO might describe how to proceed with the code or possible extensions for the code when youve just started a new project.

• IDE support: Many IDEs have adopted functionality to highlight and search TODOs in your codebase. For that reason, more and more developers assume its a best practice to add TODOs to their code regularly. For instance, the most popular TODO management extension for Visual Studio Code is Todo Tree with more than 1.1 million installs.

(Source: Todo Tree extension Visual Studio Code)

What Are the Problems With Adding TODOs to Your Codebase?

The most important problem with TODOs is their lack of context. Developers often write short TODOs that dont 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. Its even possible that only the engineer who wrote the TODO knows what needs to happen.

Moreover, TODOs dont have a clear owner except for the creator of the TODO. When you encounter a TODO when working on somebody elses code, do you remove the TODO or try to resolve it? Its a tricky question to answer. I remember experiencing TODOs as a colleges personal note that I wasnt allowed to touch.

Now lets 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 projects 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 arent valid anymore or dont 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.

How To Manage TODOs Correctly?

These guidelines are not an exact rulebook for managing TODOs because it depends on your teams preferences, size, and management style. Hence, heres a list of four tips that help you to better manage your teams TODOs.

1. Use TODOs for minor issues

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. Its 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.

2. Add sufficient context

Solely adding TODOs in the codebase is not the best way to raise issues with code. If youre 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.

3. Use a consistent format for TODOs

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.

@TODO <due date> <owner> <task details>

Alternatively, you could define more properties like references to code snippets or relevant files.

@TODO <due date> <owner> <task details> <link 1> <link 2>

When you have a consistent format, its 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.

4. Define rules for TODOs

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, its much easier to identify a microtask versus a task that requires the assistance of a project management tool.

Whats Best?

To add my opinion, Im not a big fan of managing TODOs within the codebase. However, this strategy can work for smaller teams with the right set of rules. Dont forget to provide context and identify a clear owner.

This post was written byMichiel Mulders. Michiel is a passionate blockchain developer who loves writing technical content. Besides that, he loves learning about marketing, UX psychology, and entrepreneurship. When hes not writing, hes probably enjoying a Belgian beer!
Also published on: Managing Technical Debt.