TODO comments

When you write bigger feature it takes days sometimes weeks. Plenty of new files, hundreds or thousands new line of code. From obvious reason you are focused on current module, class, method. Very often you have to also make mockup code – fully working, but without error checking, without check all necessary conditions, etc. Most of developers make it “automatically” – without thinking – just yet another piece of code used temporary to check current work. I’ll fix that later – you can think and you backs to main task.

Now, if you acted foolishly, you might regret that. What I am talking about? Well, code is just a code and you are not able distinguish between mockup and ordinary code. Is even harder to catch this difference when you are near the end of a feature. Is easy to omit missed part if method takes almost whole screen and looks good. So, what should I do? – you might ask. The answer is simple, so obvious, even typical – leave a message for yourself – and just use a comment.

//TODO dirdival: make error checking
//FIXME dirdival: is not working yet for negative values
//TODO dirdival: add missed conditions for all enum values

It might be short, it can be long (with full story and links), but the most important – it should say exactly what have to be done. Clear message, readable by other developers.

Most of editors, IDEs, support this good practice and they highlight //TODO , //FIXME comments. That technique:

• prevents bugs – and save your time
• allows quickly find places to improve, even if they are in many files
• checks how far are you from release a feature?

---

OK, how does it work in real life? Let’s take a look closer on a medium size project (~30 developers):

$ find ./ \( -name '*.c' -o -name '*.cpp' \) | wc -l
1897
$ find ./ \( -name '*.c' -o -name '*.cpp' \) -exec cat {} \; | wc -l
651965

So, we have 1897 files which weight 651965 lines. BTW, it gives us ~343 lines per one file, quite nice result. To be honest I expected something near 1000 lines. We have C/C++ here and nowadays many youth developers call them low level languages.

How much interesting comments we might have here? I check most common tags: TODO, FIXME, HACK, BUG. I assume that they are not used as name of functions, variables, etc.

$ find ./ \( -name '*.c' -o -name '*.cpp' \) -exec grep -i '\<todo\>' {} \; | wc -l
359
$ find ./ \( -name '*.c' -o -name '*.cpp' \) -exec grep -i '\<fixme\>' {} \; | wc -l
204
$ find ./ \( -name '*.c' -o -name '*.cpp' \) -exec grep -i '\<hack\>' {} \; | wc -l
70
$ find ./ \( -name '*.c' -o -name '*.cpp' \) -exec grep -i '\<bug\>' {} \; | wc -l
9

But wait a second. You said that we are using this tags in development, so what are they doing here? It’s production code.

Welcome in real world! It has limitations. Everything have limitations: Earth surface area, your life, even a feature which you are creating. In some beautiful day your Project Manager might say: Our customer said that we need that feature NOW. So here is my executive order: Push it NOW, just like it is.

OK, let’s take a look on some comments. I changed them (you know – license), but sense is preserved:

//FIXME: it doesn't work

Is not obvious, what doesn’t work? Function, your whole code from commit, your brain? Please be more specific.

//TODO: fix me

Similar to above.

//BUG: random crashes here - need deeper investigation

Not so bad info, but you should never see it in production code.

//HACK: I have no idea how to do it correctly but we have to go on production

No comment.

This list requires some comment. Of course we know about deadlines but the last three examples should never appear in main branch. Somebody didn’t say: Sorry, but we are in middle of nowhere and we can’t PUSH. This comments make me sick when I see them. But believe me – I wish see them, because opposite version, without them, is even worst.

So yes, leave a comment for other developers about your problems, ideas, thoughts about a code, but make it readable. Just after an executive order make same notes, in your bug tracking system, or force adding them by your PM. You should lave a message that not everything were done like it should.

When I said go on production it means – go on review, after that tests and push to main branch – shorter path does not exist.

---

And small reflection on the end. How you can see tags TODO, FIXME are so popular. If your source code is big and you wish use them you can meet small problem. During searching TODO in editor you might visit not only yours comments. Good idea is to have some pattern which is unique. I use my nick name:

//TODO dirdival: add error checking

Easy to find and you always know who is guilty when you see it.