3 Reasons Why TODO Comments Are a Good Thing…
For Uncovering Technical Debt Hiding in Your Code!
Over the last 20 years I’ve been an IT Developer, Test Engineer, Software Architect, Enterprise Architect, Engineering Manager, Scrum Master, Entrepreneur and Product Manager. I’ve worked full time in corporate IT and as a consultant. In those years and roles, I’ve come to appreciate how developers leave comments that identify technical debt hiding in the code.
Technical debt isn’t always a bad thing. In short, it represents a trade off made by the team to meet a near term business goal. Letting it grow out of control is what causes teams to fall behind. Disciplined developers will add TODO comments to the area of code representing the technical debt. A typical TODO comment looks something like this.
TODO comments should point out why the debt was incurred and how it should be addressed. To be more specific, most developers leave TODO or FIXME comments in the code for the following reasons.
- To leave a note for themselves to complete something later in that day or the next.
- To describe a HACK or temporary fix to refactor later when the dev team has more time.
- To describe a deeper structural/architectural issue with the code that will impede the implementation of future features.
Product owners and engineering managers aren’t usually working in the code, so they might not see TODO comments, but they need to be aware of the debt they represent. Most scrum masters say that creating new technical debt should be avoided and existing debt should be managed in the sprint backlog. This doesn’t always happen in the real world. A recent study conducted by Ambysoft suggests that roughly 48% of agile teams are actually paying down their technical debt.
I strongly believe TODO comments are an important artifact that should be excavated. So over the past five years I’ve built a few tools that make it easier to organize TODO comments, but none of them has addressed one fundamental issue. The only stakeholders who see the comments are developers. In order for the debt to be addressed within the agile process, we need the whole team to understand the state of the code and how it impacts delivery. This is why I developed the latest release of imdone.io.
When you add a github repo to imdone.io, it will integrate all your TODOs into github issues labeled “debt”. It also creates a github webhook that will run every time your branch receives a push or a PR is merged.
After imdone.io opens your issues, it’s important to go through the process of grooming them, prioritizing them into the backlog and identifying the user stories that depend on them. Only then will you understand the technical debt that’s impeding the progress of features and capabilities your business needs and start paying it back!
TODO comments are very prolific. I’ve tested imdone.io with some very popular open source projects. You might be surprised at the amount of technical debt imdone has uncovered. Here’s an example of an issue created from a TODO in the spring-framework, which is heavily used by Java developers at many fortune 500 companies.
For more examples, take a look at the imdone org repos on GitHub.
