Let's talk tech debt and code improvements. We've all been on a development team where ToDo comments are left in the code, hoping they'll be picked up during downtime when no active tickets need attention.
Table of Contents
The Downtime Never Comes
How It Is Normally Handled
Tech Debt Tickets
ToDo Comments in Code
What's the Problem?
There Is a Solution Though!Forging a Tech Debt Strategy
There's Tools to Help You!
Benefits Of This System
Conclusion
The Downtime Never Comes
However, downtime never arrives. Product owners constantly demand new features, and developers' worklists keep growing. Tech debt tickets often get lost among other priorities, leaving no time for refactors or ToDo improvements.
How It Is Normally Handled
In my experience, there are two ways tech debt or coding improvements are handled in a development team:
Tech Debt Tickets
When a developer identifies an improvement or rogue code, they create a ticket (for this article we'll use JIRA) with instructions/details.
First, not all developers are skilled in creating JIRA tickets, leading to poorly titled tickets, missing tags, or overly detailed technical descriptions.
Secondly, these poorly created tickets get lost in a large product backlog. This method only works if tickets are correctly made and tagged as "tech debt" for easy retrieval.
ToDo Comments in Code (the reason we're here today)
When developers encounter rogue code unrelated to their current work, they leave a comment like:
//ToDo: Improve this code for performance - use an object literal.
These comments are committed to the code base and visible to all future viewers.
Important: Avoid refactoring code unrelated to your current work. Mixing changes makes future reverts harder, as commits will include both task-related and unrelated code.
What's the Problem?
Many developers complain that tech debt rarely gets addressed because there is no documentation or allocated time in the sprint. These comments are often forgotten until someone stumbles upon them, lost, to only be found by chance.
They never see the light of day and the work is rarely improved, because the team aren't given the time for tech debt, or may not be working in that area of the code base for a while (where the changes requested are relevant to the ticket being worked on).
There Is a Solution Though!
Combine the two methods, adding ToDo comments as you go, using these to power sprint work, let's take a look at this in more detail.
Forging a Tech Debt Strategy
To address ToDo comments, commit to a tech debt strategy. I propose the following solution:
Decide within your team how often you'll tackle tech debt, depending on your sprint cycles.
Add ToDo comments to the codebase as needed.
Before the sprint you've committed to tackling tech debt (based on step 1) review ToDo comments. Pick 3 ToDo comments to address and complete in the Sprint and create detailed tickets for them. This ensures all relevant parties are involved and tickets are well-documented with titles, tags, and necessary technical details.
There's Tools to Help You!
Many IDE's (Integrated Development Environments) and code editors have plugins or built-in functionality to view ToDo: comments.
For example, JetBrains' IDEs view them like this:
As you can see, there are clear details around
- how many todo comments were found
- where they are located (filename and code line)
- the comment left.
If Jetbrains' software is a bit pricey for you, and you're utilising something like VS Code, there's a perfect extension called ToDo Tree which is free in the extensions library.
Name: Todo Tree
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree
And displays the results similarly:
There are many tools, plugins/extensions for many other editors too, so you're not restricted.
Benefits Of This System
Easy to add at the time: - Comments are simple to write and add whilst at that place in the code, creating a virtual bookmark.
Doesn't break concentration: - Being able to add the comment there and then whilst you spot it, allows a fire-and-forget approach to the change/improvement. Rather than having to break off, login into JIRA, create a ticket, remember the tags that needed to be added, and fill all the details in, just leave a comment and continue with your thought process.
Often "code smell" doesn't get recorded because developers don't want to go through the laborious task of creating a ticket when in the middle of a coding flow.
Add Prefixes to categorise: - An approach I've implemented in previous teams, is adding a tag/prefix to your ToDo comments, to help prioritise, or group comments (these would be pre-determined by your team, as not to create repeat or meaningless tags).
Some examples could be:
- High / Medium / Low => priority-based improvements
- "Security" => indicating a security improvement
- "Styling" => improvement around code style
- "Performance" => improve performance, e.g switch case to object literal
- "BP" => best practice e.g. variable naming, code layout, usage of particular functions etc.
Example of how these would be used:
// Single Tag
//TODO: Performance - update this switch case return, to utilise an object literal lookup`
//Combine tags
//TODO: High, Security - update this function to factor in exposing API secrets
Using various tools' filtering ability means sprints can be focussed on tackling particular types of tech debt, or higher priority issues using the pre-determined tags.
Conclusion
Addressing tech debt and code improvements is a constant challenge for development teams. The traditional methods of handling tech debt, such as creating JIRA tickets or leaving ToDo comments in the code, often fail due to a lack of documentation, prioritization, or effective follow-up. However, combining these methods can create a more efficient strategy, meaning that tech debt is dealt with regularly.
By integrating ToDo comments with a structured approach to tech debt during backlog grooming sessions, teams can ensure these improvements are systematically addressed rather than on an ad-hoc basis. Utilising IDEs' built-in tools or add-on extensions can further streamline this process by providing easy visibility and management of these comments.
Ultimately, a committed tech debt strategy that includes regular review cycles, prioritisation, and commitment to resolving comments can help teams manage their workload more effectively. This approach not only maintains code quality but also ensures that necessary improvements are not overlooked, fostering a more sustainable development process.
As always I'd love to hear your thoughts and opinions on this topic. Feel free to follow for future posts.
For more tips, discussions, and to hear about other posts I make elsewhere drop me a follow on Twitter.
Top comments (4)
A great, well-thought-out post, Grant! Very important to make sure that those todo comments are in fact technical dept, not "would like to have" or "do not forget to do this". It reduces unnecessary comments.
Thanks, yeah it’s very important to have your team get a clear definition of what the todo comments are for.
This is why I like the priority approach also. It allows those “nicer reactors or improvements to be noted, but they’re lower priority” things like, update this function to be more performant vs convert these functions to a service for example.
Well written blog with a sensible approach to a very common lifecycle problem. Question is why don't we do it. I'm going to use this approach in my next project.
We often don’t do it because it isn’t “the norm”. Often teams , project managers and product owners are too focussed on churning through tickets related to features they don’t allow time in the sprint for any improvements or tech debt.
As a result over time the code becomes unmanageable , harder to refactor and as a result often the phrase “it’s beyond help” and “it’ll be easier to just rewrite it”. However it never happens, so I urge teams to recognise the importance of regularly tackling the tech debt, refactors and “easy wins” often.
As, soon enough chipping away 3 tickets at a time, it’ll be clear or at least a lot more manageable.
This approach also is not to be confused with bug handling.