Why TODOs and Jira Tickets Are not Working Anymore

Problem

A significant amount of a developer’s day is spent reading and understanding code written by other developers. You are essentially stepping into the mind of another developer. It can even be challenging to understand code you’ve written yourself after a few weeks of not working on it. Without the proper context, stepping into another developer’s mind becomes increasingly problematic. Just count the time you spend looking for documentation and asking teammates for context, not to mention the time spent in meetings.

The time spent doing this is a problem in itself but it becomes much worse if the code contains issues that need to be fixed. According to a report by The New Stack, developers spend 32% of their time fixing the past, rather than building the future. Another blog post by Nnamdi even suggests a number up to 42% if you combine managing technical debt with the time spent fixing “bad code” (debugging, refactoring, etc.). 

Just imagine how much more productive your development team can be with better codebase communication.

So, why is it not easier for developers to share and consume context and insights about the codebase issues with their teammates?

What are the solutions today to improve codebase communication?

Most developers can relate to the following two solutions used by development teams globally: creating tickets or TODOs. But why do these solutions not work to improve codebase communication?

• Create a ticket or raise the issue with a team member.
  

Engineers are always strapped for time. So, unless the issue is critical, it will be recorded in a product or task management tool and placed in a backlog, never to be seen again. By recording the issue, developers think they have done part of the work and will address the issue in future sprints. However, recording the ticket is only 10% of the work.

A golden rule that you can apply is based on the 2-minute rule. The 2-minute rule says that you should do a task if it takes less than 2 minutes of your time. For engineers, 2 minutes is not enough to solve an issue. Therefore, the golden rule here is the 15-minute rule. If you can absorb an issue's context and solve it within 15 minutes, you should do it. When an issue requires more time, it will interrupt the flow of the current issue you’re working on.

Also, if you decide to record the ticket, you’ll have to step outside your IDE and into a product or task management tool. By recording this issue outside the codebase, you lose visibility over the issue. You will most likely forget about it until you reencounter it when working on another issue or feature. To retain this visibility, developers often opt for the second solution below to improve codebase communication.

• Create a TODO.
  

Many developers still like to create TODOs to remind themselves or teammates about unfinished work or problems within the codebase. As explained above, a TODO ensures better visibility for issues that need to be resolved in contrast with a product or task management tool.

However, TODOs lack fundamental properties to improve codebase communication. First of all, the engineering team’s often don’t have a standard for TODOs, let alone capturing context. A TODO is often a quick and short blurb of text and usually does not capture a lot of context about the issue. For that reason, TODOs are unusable for anyone apart from the creator.

Another problem is that TODOs are seen as “personal”, especially with the introduction of tools like GitLens that show the owner of a snippet of code or the person who has last modified it. Therefore, team members will naturally ignore it as “not my problem.”

And lastly, TODOs are flaky and expire quickly. If code is moved between files, the owner can disappear and make it even harder to track down what has happened or where the TODO originally came from. With older codebases, especially open source ones, you might notice that they have many floating TODOs nobody understands, knows where they came from, and whether they are still relevant? The code might have changed so much that a TODO has become obsolete. Just think about codebase refactoring. Do you want to be the person that tries to figure out if a TODO is still relevant? I guess not!

So how do you improve your codebase communication?

Engineers spend ⅔ of their time in the editor. If you want to influence how they communicate, do it where they’re already spending most of their time. Therefore, with the rise of extensions, it has become easier for developers to stay within their development environment and not have to switch between different tools. For instance, simple extensions like Excel Viewer help developers to visualise CSV files in their IDE to avoid switching between tools.

That's why codebase issues need to be visible in the actual codebase for two reasons: 

1. Engineers are reminded about them when they are browsing code, increasing the likelihood of bringing them up, adding details, and eventually addressing them.
2. Engineers are constantly reminded about issues directly related to code that they are currently working on—potentially alerting them to issues that they can make worse.
   

The most essential characteristic of a tool that tracks issues within your IDE is the ability to record context—linking relevant code, adding a detailed description and code, and linking related issues. By providing this context, an engineer is more likely to address the issue when it affects the code they are working on.

If you’re looking for a sustainable solution for tech debt management in your engineering team, you need Stepsize. It’s the world’s first and only bespoke tech debt management tool. Track and manage issues directly from the IDE, and create issues directly linked to code. For engineers, this means no more context-switching and high-quality issues that can be prioritised based on impact and fixed. And because it integrates with Jira, your PM will love it too.

‍Learn how to get started with Stepsize here. It works with Visual Studio, VS Code, JetBrains. You'll be able to:

• Create, view, and prioritise codebase issues directly from your editor
• Add issue to your sprint with Jira integration
• Collaborate with your team to improve your codebase health

Conclusion

As stated by The New Stack, there’s a huge opportunity for organisations to find new ways to decrease the percentage of time engineers spend on fixing issues and increasing time spent on writing new code. One major way to decrease the percentage spent on fixing the past is by visualising issues within a codebase and recording context. You want to avoid floating TODOs at all costs or populating backlogs with undescriptive issues. Once you can successfully implement this, developers will have more time to build new features, improving their team’s output.