TODOs and legacy code

So today I was working on a little side project at work. The project involved trawling through the code base for all TODO's, FIXME's etc and evaluating whether or not the comments were still relevant. It would be worth mentioning here that the product I work on is a large code base that has been live for about 14 years, slowly evolving over that time. There is code that pre-dates all the 'standard' things that I have learned during my university and my work experience so far.

So back to today, I got cracking to see how many things there would be in my list. 1063. Wow, this really felt like a lot. I tried to reason that this was actually not too bad, considering the code base is almost 1 million lines long, but damn if I didn't go and make a brew to consider my task.

Tea in hand I returned to my desk, and started to analyse the results. I was happy to discover that the bulk of the todo comments (~700) were actually a form of annotating that the method was overriding a method in a parent class from before override annotations were a thing.

Result!

Boosted by this I set about the remaining comments with increased optimism. This didn't last however as the rest of the TODO's were a weird and wonderful bunch. A few helpful ones that just said nothing, some where you could feel the original developer letting off steam with a useful //TODO NOOOOOOOOOOOOooooOOooOO!!! However just over 200 of the remaining TODO's I had to mark as 'requiring further investigation'. These will be given to the senior developers to look at further.

In all, it took about 5 hours to complete my review and hand it off. The overriding lessons that I took from the exercise was:

1. Don't write TODO comments
2. If you have to, you will forget about them before you get back to them
3. You will write something that makes sense to you then, and only you at that time

So if you ever feel the need to write a TODO, and you really have to, then make it more explicit and verbose  than you think will ever need. Future you, and more than likely some poor soul years down the line, will thank you for it.

Happy commenting,

S