You are coding away and things are flying by. You are in the z o n e. Nothing can stop you now. And then, of course, it hits you. It kind of sneaks up from behind. A special case you did not really think of. You just discovered a special case that might cause some problems. – “What … how did this … awwww”. It is late. You want to go home and need to check in. This will have to wait. This can be taken care of later.
You write: “TODO: this should be refactored to a visitor pattern.”
And yet another TODO sneaks itself into codebase.
Have you seen these kinds of comments. Small memos to fellow coders. A lot of them? Maybe you add them yourself from time to time. TODOs can be quite useful but I usually see them being abused and tossed around code bases like IOUs. Like an expensive loan. You are putting yourself in technical debt.
Some time ago I investigated a code base and found over 300 hundreds of them. This kind of behavior usually turns up whenever stress is involved. Either because there is something ‘more important’ on the menu or or you have over committed and you might feel like your lagging behind.
Either way your work is not getting the attention it deserves.
In situations like this a TODO list is probably a more effective approach. At least if it is used and managed properly. Adding comments in code thus making them a second class citizen in an environment where they do not belong is not the proper way to manage TODOs. These kinds of lists needs to be visible and constantly updated.
If there is a lot of work to do, say you have ‘inherited’ a legacy code base. Instead of writing more TODOs, you could note large refactorings, design changes and improvements on Post-It’s. Sticking them up on a wall so everyone can see them. Constantly reminding people on what to look out for. What to improve. But sticking a few hundreds up on a wall would look ridiculous, and it is.
Do not transfer your TODOs to stickies. Investigate you code base and note the top 5-10 ones, that need the most attention, so everyone can see. Putting more than a dozen up will probably be discouraging.
Back to the codebase with over three hundred TODOs then. Think of a wall with a Post It for each and every one of the TODOs. That would be quite a wallpaper right. You would not want to be the one to put another one up, right? Metaphorically speaking.
No, instead you need to remove one. You need to be the first one to take a step in the right direction and start cleaning up. And you need to make everyone else do the same too.
Whenever a code base has more than 2-3 TODOs it means you have some unfinished work. If you have more than a dozen it is very likely that problems are lurking very near. And your task is to remove these impediments as soon as you can. Look at it as lowering the water to be able to see rocks as you navigate a boat through a particularly rough area. If you can see the rocks, navigating the water is much faster, easier and a lot safer. And probably more fun too.
Visualizing and managing these kinds of problems, future refactorings, design changes, TODOs or what ever you may call them is important. Even more so if you are sharing a code base with others. Do not let your colleagues or your future self stumble upon unfinished work. Instead let everyone know early that something is not thought through enough or can not be solved in a proper way. It is OK not to be able to solve every problem in a perfect way. Hiding and obscuring that fact, is however not.
TODOs are unfinished work, waste, and should be treated like it. Waste has no place in an effective software development process. Start removing it today.