There are many way to gauge the quality of software – some are scientific, like cyclic complexity, and others less so. One of the less scientific methods is to look through the comments and see how many times TODO, HACK and similar tags appear. The more they appear, the lower the probable quality of the software.
You might wonder why I think this – after all, surely TODO is just an indication that the developer(s) were being forward-looking and planning for the future, leaving suggestions for themselves or other developers when the time comes to make changes. Similarly HACK is an admission by a conscientious developer that the code works, but could be improved upon; a humble gesture by a developer who knows that they’re not perfect, and a promise that they’ll return at some time in the future.
It might appear to be the case, but the reality is almost the complete opposite.
What Does a TODO Tag Really Mean?
When you see a TODO statement in source code, it tells you the code isn’t complete. Unless you actually wrote the code you don’t know quite why and, let’s be honest, even if you DID write it, if more than a few weeks have passed then even you probably can’t remember why.
In theory the text of the comment SHOULD tell you exactly what needs to be done to complete whatever feature the code is related to. It almost certainly won’t though. Comments I’ve seen range from the useful hint (“this needs to be refactored”) to the somewhat pointless (“I don’t understand why this doesn’t work”) to the more dictatorial (“Change this to use a dictionary to hold the objects and access via...”, “Don’t change this!”). The useful hint type of comment sometimes points you to things that can be done easily while you’re working in the same general area, others can be more “problematic”.
By problematic, I mean they can actually reduce your productivity. This might seem extreme, and you might wonder how that could be.
Imagine the code contains a comment like “TODO: Replace this array with a list”, but you decide to do something different. Maybe you leave the array as it is, maybe you replace it with a sorted list, a dictionary, or maybe you just decide to refactor that area of the code completely. Then, at the code review, imagine you have someone who doesn’t trust anyone but themselves, and feels everyone should just follow orders. That comment was really an order – didn’t you notice? And it was written in the code, which gives it a certain gravitas, certainly enough to make its instructions outweigh your meagre skills. But you did something different, so now you get to explain exactly why you dared to go against the instructions in the code and used your own intelligence and skill to solve the problem.
You probably think I’m exaggerating, but I’ve seen it happen a lot, and I know plenty of other developers who have seen it too.
Before you even start to make changes that may or may not be prescribed in the TODO comment(s), there should be a reason to actually make those changes. If you’re using agile development, changes should be required as part of a story. If nobody actually wants the code changed, and if changing it won’t actually achieve anything positive, then there are probably better things for you to spend your time on. But still, you were distracted enough by their presence to waste time thinking about them.
So, just having the TODO comments in the code tends to cause problems. The ones that might be helpful are usually offset by the ones that cause nothing but trouble. If they weren’t there, you could just feel free to use your own judgment to make the changes you needed to.
What about HACK?
HACK is almost never any use apart from letting you know that someone didn’t write the code as well as it should have been and didn’t get around to fixing it. It’s a more specific version of TODO, and of even less use.
So, Are There Any Places TODO And HACK Are Acceptable?
Despite everything above, TODO and HACK CAN be useful. If you’re making changes to a system, those changes may need to be made in several areas of the code. This is especially likely if you’re working on an agile story, which would normally be focused on a feature rather than a specific part of the code base.
As you make changes on your branch of the code, TODO tags are a good way to keep track of the things you need to do. It may seem to go against what I’ve been saying, but there’s a difference; in this case you’re using TODO tags to tell yourself to do something, you’re not doling out instructions to someone else.
As you work your way through and complete the changes, remove the TODO tags – your IDE will usually help you to find them. When you’ve finished and are ready to merge your changes back to the main branch of your source control system, ideally you’ll have no TODO tags left, because your changes are complete and you haven’t left anything outstanding.
But There Are Already TODO Tags in the Main Branch!
This is quite probable, especially with an established code base. The best way to approach them is to consider them as indicators of technical debt, gradually refactoring them out and their related code out of your code base.
Summary
TODO and HACK may seem useful, and in some circumstances they are. But in too many situations they can turn into dictatorial orders thrown at future developers, who then have to consider them no matter how irrelevant the passage of time and changes to the system have made them. Treat them like manure; they’re useful spread round your own yard, but if you start throwing them at other people, you’re going to lose friends quickly.
