Why TODOs and Jira tickets are not working anymore

👋 Hey dev.to community! I've launched a quick survey to learn more about how modern Engineering teams communicate, and would really appreciate your input!

Please, answer a few survey questions, share your opinion and get a chance to win an Amazon gift card worth $100💸

Now let's look at why TODOs and Jira tickets are not working for engineering teams anymore!

The 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.).

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.

Image credit: Jason Goodman on Unsplash.

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

For that reason, 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.

The best way to get started with creating code issues is to install the free Stepsize extensions for VSCode, Visual Studio or JetBrains. The extension will help your Engineering team:

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

Try to avoid floating TODOs at all costs or populating backlogs with undescriptive issues. Once you successfully implement this, your engineering team will have more time to build new features, improving their team’s output.