TODO or not TODO / Stop spamming the code with useless comments
It has been proven that the best way to solve a complex task is to divide it into smaller tasks. Some people create a to-do list in a notebook, some draw a diagram, others prefer to keep the plan in their minds. And, of course, many of the engineers use TODO comments in their code, not to forget something.
What may go wrong? One //TODO: here and one //TODO: there. But as a result – no one ever takes care of those comments. Everyone is afraid of touching them: what if it is something important? There is always an endless list of tasks in the task manager, and there is no task to treat the abandoned TODOs. If you haven’t observed something like that, are you sure? (Lucky you!)
“What is she talking about?” – you may think, as these types of comments are extremely popular and an absolutely normal thing.
I will share some examples with you.
// TODO: log result
It will take 15 seconds to write a log.
// TODO: add test
It will take 5-10 minutes to write a test.
// TODO: verify result
It is your responsibility to verify if it is working, and it also does not take that much time. Do it now, not later (which means never).
//TODO: fix
You have found a bug and just left the comment, so no one has an idea that something is broken? Please, go and create a ticket with the problem description. If the problem is not on the board, it doesn’t exist.
//TODO: check later
Check what? When? By whom? Why? Why not handle it now when you’re in the context?
By leaving such comments, you shift responsibility from you to another person who will find this comment. Besides, you provide absolutely no context.
How to use TODOs properly?
If you want to remind yourself about something you don’t want to forget, or you are waiting for some details while working on the task, it is completely fine to use the TODO comments. It’s even a good idea, because human memory is not very reliable. Just make sure to take care of these comments before you merge. It should be living within the scope of the current piece of work.
If it’s a 5-minutes-job, just do it. If it’s a bug, create a ticket. Need some additional information, ask for it. But do not postpone a problem for the future.
A hack from me: write preconized todos, like todo-julia, and create a filter for the IDE to show your specific todos. It helps to filter your comments from others.
Another scenario is when you want to warn your teammates or your future self about something critical and unobvious that needs to be implemented on the next iteration of the task, and cannot be implemented now because of some circumstances. And you feel the need to have it not only in the ticket, but also in the code to be more specific about something tricky. If the comment is meaningful and concise, it is fine. But it should not last forever. The purpose of the comment should be to help, to guide, not to confuse.
TODO or not TODO – is your personal choice. A perfect code base does not exist, but you can contribute to making it cleaner.
