TODO Comments and Technical Debt

By Shahed C on July 21, 2013

When I first started out in software development, I used to write a lot of comments in my code. To stay consistent with the developers who had previously worked on the same code, I even added to the historical comments above each module.

As a result, the top of a VB module could look like this:

' ****************************************
' Module: EmailProcessor
' Purpose: Process Email
' Author: John Doe
' Last Modified By: Jane Smith
' *****************************************
Sub ProcessEmail
  ' process email here
  Call ProcessEmail()
End Sub

Over time, I’ve learned that comments should be used sparingly, and well-written code should reveal its intentions without requiring any comments. Jeff Atwood’s blog post from 2008 covers this:

http://www.codinghorror.com/blog/2008/07/coding-without-comments.html

“While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.”

An exception to the “no comment” rule is when you have code that needs some explanation even after you’ve simplified the code as best as possible. Another exception is the dreaded “TODO” comment and the technical debt that it causes.

Sure, you should commit working code into your source control system and remove dead code. But what about adding reminders in your code?

If some code needs to be written, you can either:
(a) write it now if it needs to go in immediately
or
(b) write it later if it should be deferred

In reality, it’s not uncommon to find “TODO” comments sprinkled throughout application code, maybe even more so in legacy code. Many developers even follow a convention to prefix their TODO comments with a particular syntax.

//TODO: don't forget to fix this code

Visual Studio even has a built in Task List viewer that can be filtered by “comments” so that you can quickly identify all your TODO comments.
http://msdn.microsoft.com/en-us/library/txtwdysk.aspx

Simply click View –> Task List from the menubar, then filter the results by “Comments”.

View Task List: Comments

In fact, this feature has been around for several versions of Visual Studio.
http://msdn.microsoft.com/en-us/library/zce12xx2(v=vs.80).aspx

Comments like these tend to accumulate over time, and become a part of your Technical Debt. In order to prevent this from happening, you should consider using the Tasks List to identify these TODO comments during code reviews. This will help you clean up your code periodically and keep it clean.

For more information on Clean Code, I would highly recommend Robert C. Martin’s classic “Clean Code” book. It focuses on Java developers, but is also useful for C# developers.
http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

 

2 thoughts on “TODO Comments and Technical Debt

  1. Dave Voyles (@DaveVoyles)

    The book looks great. I love recommendations like this!

    I have mixed feelings about comments. When I do tutorials, I comment like a mad man. Same thing on quick projects.

    As long as comments aren’t obvious, then I have no problem with them. The problem I see a lot of devs run into, especially senior level, is that they never comment and just assume that the code says what should be understood.

    The problem with that, however, comes into play when a new engineer has to dive into the code, and the one who initially wrote it is long gone. Who do I ask? What was their initial intention?

    Even worse is when they use one letter, or ambiguously named variables. Agggh!

    Reply
  2. Shahed C Post author

    There’s no excuse to use cryptic variable names these days. Instead, new code should have descriptive variable names, and methods should have low cyclomatic complexity.

    When working with legacy code, consider refactoring blocks of code that you touch. Or at least, include a brief comment to explain the code if necessary.

    Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.