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 centralized 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? What’s 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 doesn’t affect the new feature directly, so you note it to remind yourself. It’s 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 it’s 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: I’ve 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 project’s 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 you’ve just started a new project. : Many IDEs have adopted functionality to highlight and search TODOs in your codebase. For that reason, more and more developers assume it’s 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. IDE support (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 don’t give a lot of contexts 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. How To Manage TODOs Correctly? 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. 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. 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 2. Add sufficient context Solely adding TODOs in the codebase is not the best way to raise issues with code. If you’re looking for ways to organize your issues and add context, try out . It allows engineers to import their TODOs into the platform, to organize them and add context such as linking code, dependencies and add metrics such as hours lost. Stepsize 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> <task details> < > owner Alternatively, you could define more properties like references to code snippets or relevant files. @TODO <due date> <task details> <link 1> <link 2> < > owner 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. 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, it’s much easier to identify a microtask versus a task that requires the assistance of a project management tool. What’s Best? 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. This post was written by Michiel Mulders . Michiel is a passionate blockchain developer who loves writing technical content. Besides that, he loves learning about marketing, UX psychology, and entrepreneurship. When he’s not writing, he’s probably enjoying a Belgian beer! Also published on: https://www.stepsize.com/blog/how-to-organise-your-todos-as-a-software-engineer

Asana

Technical Debt Horror Stories Shared by Developers (Part 1)

4 Tips on How to Refactor Code in Visual Studio Code

Track and prioritise technical debt. Create your free account at stepsize.com

Get the AI companion for software projects. Never miscommunicate again

Nominated for 2022 - HackerNoon Contributor of the Year - Frontend

Nominated for 2022 - HackerNoon Contributor of the Year - Code Quality

Nominated for 2022 - HackerNoon Contributor of the Year - Coding

Nominated for 2022 - HackerNoon Contributor of the Year - Refactoring

Too Long; Didn't Read

Make resilience your competitive advantage

4 Ways Software Engineers Organize Their TODOs

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

10 Best JetBrains IDEs Plugins to Boost Your Productivity in 2021

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

10 Best JetBrains IDEs Plugins to Boost Your Productivity in 2021

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps