How I deal with TODO comments in code


Posted by Steven

„TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.”  - Robert C. Martin, “Clean Code – A Handbook of Agile Software Craftsmanship”.

I absolutely agree with Uncle Bob. However, in my experience TODO comments are one or more of the following:

  1.  Tasks that will never be solved – “Don`t have time now, will do it later” where later equals never.
  2. Cryptic thoughts from developers that left the team long ago.
  3. Obsolete because the issue has long been dealt with.
  4. And, the worst I’ve seen so far: Conversions / discussions between developers. They can go over 10 lines and more as each developer begins his statement with a TODO or a FIXME. This discussion obviously never reached a conclusion; hence the comments were left in the code.

Obviously there is a mismatch between the good policy described by Uncle Bob and the reality I’ve experienced. I deal with my TODO comments by

  1. Making them “mine” by adding my initials to them like “TODO SSC This has to be implemented”.
  2. While developing, I try to commit into version control as often as possible. Before the final commit of a feature, I do a full text search in the whole code base to find “my” TODOs and fix them. My goal here is to never commit TODOs permanently.

That best method has suited me well. If everything goes as planned, I can be sure that never a fellow developer will walk up to me, yelling “You wanted to do this but you have not! Now I have to understand your weird thoughts!” A reassuring feeling.

EDIT: Johannes wrote a nice article about comments, too.

Share: