Brendan Enrick

Daily Software Development

TODO Comments - Code Audits #9

When writing software, we often have to write comments to explain why we did something.  I try to write my code such that I don’t have to comment it. In fact, anything other than a temporary (less than a few minutes) comment I write, I consider to mean that I made a mistake.

We could get into endless discussions of when we should comment, what we should comment, and how much we should comment. I’ve had plenty of discussions about comments with people with various opinions on the subject.

An interesting feature of Visual Studio is that it lets you create a list of “tasks” by leaving yourself comments that begin with “TODO” or “HACK”. In some ways I like those comments, because they build into the code reasons for why the code is the way it is.

If you write “TODO”, it tells the reader that the code is incomplete and that wasn’t intentionally left the way it is. There just wasn’t enough time. If you write “HACK”, it admits that you wrote the code badly and it needs to be rewritten.

These types of comments fit in very well with what I tell people about comments. Each one I write and leave in the codebase means that I didn’t write the code as well as I wanted to. Each one is my mistake. The more comments I write, the worse the code is.

The Bad

One codebase that I was working on had a lot of these comments. It seemed they were all over the codebase. There was the other problem that copy-paste coding was rampant, so I am sure that many of these were copied and pasted from previous locations. Heck some of the even said to remove the duplication. The irony? Those comments about removing the duplication were copied with each new instance of the code that was copied.

I checked Visual Studio’s task list of these comments just to see how bad it was.

1131. 1131 tasks that were indicated with “TODO” and “HACK” comments. That takes more than just writing a lot of these comments. That requires writing them and never going back to fix them or complete them.

The Better

Check your codebase right now. Do you have any of these comments lying around? Is it only a handful? If so, you should go try to clean them up. That’s easy and will help you out down the road.

Anytime that you’re going to write a “TODO” comment, think about why you’re putting it there? Is it something that’s really needed? If so, make yourself a note somewhere else. Add a story to go back and make the change later. Get it in the system where you really track your work.

If you know that you’re not going to get to it any time soon, don’t bother with the comment. It will only clutter up your system. If it’s not important enough for you to come back and get it soon, why are you even recording it? If it’s important later, you will be working in that part of the codebase again and you can go back later and fix the code as part of your other work.

Certainly once you get that many of the comments, you should have long earlier realized that there is something that you need to work on. That’s just a ridiculous number of TODO and HACK comments for one codebase.

Has anyone ever see more than that? Anyone think I am crazy or wrong? Tell me about it in the comments!

More Code Audit Nuggets

Keep watching for more interesting nuggets of stuff that I’ve seen in codebases.

Comments (2) -

  • George

    7/17/2012 2:43:56 AM | Reply

    You are right, but for this to happen the project manager has to be open-minded - he should let the developers allocate time for refactorings, should see the value in that, should let the developers have an opinion on the task estimates and not impose some arbitrary hard deadlines. Very few developers are willing to work overtime in the evenings and weekends just to improve thecode quality and get rid of those TODOs.

  • Brendan Enrick

    7/17/2012 10:43:52 AM | Reply

    You're very right, George! It often does involve buy-in from more than just the devs. If the project manager is OK with having lots of HACKs and TODOs littering the DB, developers will have a hard time getting things cleaned up.

    If you're constantly dealing with harsh, arbitrary deadlines, you have bigger issues in your organization than just some code quality.

    I always recommend using the Boy Scout Rule, because you don't have to put in much extra time. You use a little bit of your slack here and there to keep your code in good shape.

    You will not be able to get everything into great shape, but you'll be left only with the big refactorings left to complete. Those are the ones with big enough impact that scheduling a time to fix them might make sense, depending on how they're impacting the maintainability of the code.