Another empty can of coke. Just a few hours left before the week-end!! This is looking great, I just have to refactor this small part of the code. Two minutes and I should be done.

Ok. it’s actually more complex than I had thought. 2 minutes won’t cut it. If I refactor this part, I also have to refactor this as well. And there’s no unit tests on that part so I’ll add those. Oh, but this should really be an abstract class. It doesn’t make much sense otherwise. It’d be so much cleaner. Allright let’s see… Ugh, it’s already 6:30pm. Friday night. Everyone has left. My feature works perfectly already. Allright, I’ll just postpone this and get it fixed in the next release. I’ll add this to make sure I don’t forget:

//TODO: refactor the static report helpers.

Having marked my feature as Fixed/Ready in JIRA, our QA then validated it and it all went to production. The next monday I had forgotten about it. I was already working on something else. That TODO comment, along with the piece of unrefactored code were left to accumulate digital dust and slowly turn into legacy and mysterious code.

I never went back…

That was 3 years ago. I stumbled upon that TODO yesterday by chance, as I mistyped the name of a class I wanted to open in my IDE. It took me by surprise and I was amused to recall how I had left it years ago with the good intention of fixing it. I then proceeded to search for TODOs in our code. We have a big code base at Qualys: a few million java code lines and about a million javascript code lines. I never thought we had so many TODOs. Reading through them was like going to a museum. I’d see names of people who’d left the company years ago, I’d see code that noone wanted to touch because noone quite knew the impact it would have. I felt like Indiana Jones looking through the ancient ruins of the undone…

Was it just us? I took a peek at github’s code base:

https://github.com/search?o=desc&q=%2F%2FTODO&ref=searchresults&s=indexed&type=Code&utf8=%E2%9C%93

50,399,137 references and going up every second. If fixing a TODO would take 1h, it would take more than 24000 years of work to complete. That’s a lot of jobs right there!

As more and more code gets written every day, that number will keep growing with time. And while they can serve a good purpose, I’ve come to the personal conclusion that TODOs are hard to get rid of and should be avoided if possible:

1/ TODOs are personal. People don’t fix other people’s TODOs. When your write a TODO, you’re mostly saying to others: “Don’t worry, I’ll do this”.

2/ TODOs usually take a lot of time. If not, they would have been fixed on the fly. They also require to understand the big picture.

3/ TODOs are obscure. They are generally mystic comments that don’t give the how nor the why.

How do you deal with dusty TODOs in your code base? Thinking about it, I will do the following from now on:

1/ Don’t procrastinate great code. If you feel that a refactoring is important, then you are at a point where you have grasped the whole picture. Fix it now before moving your mind to other things. Take the additional time if you have it.

2/ If you cannot fix it now, track your TODO somewhere else than your code. Open a JIRA ticket, a Github issue, assign it to yourself, describe the why/how. Give yourself a deadline to fix it, and make sure you do it.

Leaving TODOs in code is like publishing incomplete code. It’s annoying and irritating, just like someone who starts a sentence and doesn’t