6/04/2015

Should Code Have "Come Back to this Later" Comments?

We did this today.

    # HACK: Fix this later, this is awful
  ssh $USERNAME@$TARGET '
    for file in $(grep -rl some-string-we-need-to-replace /some/directory/to/do/work/in)
    do sudo sed -e "s/some-string-we-need-to-replace/the-string-to-replace-it-with/g" -i $file
    done'

I'm not particularly proud of writing code of any kind that has these kinds of statements in it. I tend to repeat the mantra "If we don't have time to do it right, when will we have time to do it over?" in my head somewhat repeatedly. I've even known to say it out loud on occasion. And yet, here I am staring at a bash comment with the big green word HACK in it. I plan on doing the walk of shame later, for now I'm going to explain why I feel like there's a few of important rules to assume when you're writing code at work.
  1. You're never going to come back to code that you write "I need to come back to this later" in the comments. While this may not always hold true, in general if the software "works" as is, you're going to have a very difficult time convincing your boss/customer/whoever that you need to go back and fix it if they don't see anything broken to begin with.
  2. Any time you do write "TODO", "FIXME", "HACK", or your favorite word that is supposed to make you fix it later, you need to make your boss/customer/whoever understand that you do need to take the time to go back and fix it later. This is usually very difficult.
  3. Sometimes real deadlines in the release environment make it so that we have to cut corners and just get something deployed. We don't have time to do it right, right now, because we have a customer waiting for it. Just be ready to do it over when something unexpected happens because of your TODO, and be ready to get a good bit of egg on your face if it does happen in the wild. Be VERY selective about how and when you use TODO statements in your code. Production code with TODO in it doesn't seem like it belongs as production code (to me).
  4. There's an exception where you're doing something like "TODO: Need to make sure to remember that when we're implementing feature AWESOME-1234 that this is the right place to put controller/domain/dao/magic logic." TODO reminders about future new features are OK, most of the time.
We all have to write code we're immediately sickened by when our fingers type it. Hopefully we all find ourselves in roles where we don't have to do it all that frequently. But, it does happen (see: http://www.commitstrip.com/en/2015/05/29/always-stuck-somewhere-in-my-head/) - so we need to be careful about how we exercise our powers of evil getting things done. Otherwise we may end up writing "TODO: Find new customers because the old ones don't trust us any more" - and nobody wants to have to write that.

JSON Jason