skip to main | skip to sidebar

Sep 9, 2008

Quit Commenting Out Dead Code

If you're one of the guilty parties who leave dead, commented-out code in the code base please stop.

Seven reasons to delete dead code:

  1. It's dead.
  2. The dead code is only valid/useful in it's original context and as the code continues to change that context will quickly disappear.
  3. It's in source control history anyway (in it's original context). You are using source control aren't you?
  4. When you checked in your changes to source control you should have noted in the comments box that you deleted the code and why (assuming the deleted code was important).
  5. In the future neither you nor anyone else could really trust that the code is valid even if it does need to be put back in place; it's probably just as fast to rewrite it as to validate it.
  6. If people do need similar functionality they might be tempted to use the commented code as a crutch without really understanding what it does, and when they do really bad things will happen.
  7. The code will stay there... forever. No one else will delete because they won't know why it was removed and they'll be afraid it contains some magic bullet that may be needed sometime in the future (after all it must have been left there for a reason). In three months even you won't remember why you removed it, your comments will seem unclear and you won't delete it either because you'll be just as afraid as everyone else.
I'd like to jump back to number 4 right quick... you are filling in the source control comments when you check in a file, aren't you? This takes 60 to 90 seconds tops and really improves the value of your code history. When someone looks at the comments they should see at a minimum the ticket or project number (or emergency situation) that instigated the changes and a 1 to 3 sentence summary of what you did.

And don't cheat and check in 60 files at once and put "updated for ticket 0974". Though this is better than nothing, in most cases checking in each file individually and commenting on that file in the context of the ticket is much more useful e.g. "ticket 0974: added a link to header menu to point to the new analysis engine (only available for administrative role); fixed menu formatting problem; removed commented, dead code from my previous changes.". Now if someone reviews you're changes they can look at your comments, do a file compare to the previous version and understand exactly what you changed and why.