Why Signing and Dating Code Comments is a Good Practice
I’ve been signing and dating my code comments for a couple of years now. I started doing it because it seemed like a good idea at the time. First, you should be aware I believe most comments should explain why instead of what. The why comments comprise the vast majority of my comments and those are the ones I sign and date. It’s like a simple signature for code.
For example:
# This Combustible model class was originally designed for the '2012
# Exploding Things' promotion. Only the objects/fields required for this
# promotion were put into the data model but it is intentionally generic
# enough to be expanded upon to create a more robust explosion system in
# the future should the need arise. Only the most basic relationships and
# validations are included at this point.
#
# --mluton (2012-01-11)
This is helps for a couple of reasons. First, people reading this in the future (myself included) will know who’s responsible for the decisions that went into this chunk of code. Experienced developers know that simply being aware of who originally wrote something can tell you a lot about the kind of thinking (or lack thereof) that went into the design of it. Version control tools can tell you who touched specific lines over the course of time but a signed comment will give you a better idea for who truly responsible for it. A subtle but important difference.
Secondly, it tells you how fresh the decisions are that went into the code. If you’re dealing with a particularly convoluted piece of code it’s nice to know if originally developed two years ago, two weeks ago or somewhere in between. If it was two years ago chances are good you have more freedom to challenge those decisions and rewrite it to conform to more current needs. Or not. Either way, it’s useful information to have.
Often times developers will comment out code instead of deleting it because they have reason to believe the removal is only temporary. Uncommenting it later is much easier than looking through commit logs for the old code to restore. However, many times the removal does indeed turn out to be permanent but the code stays in the source file commented out forever because nobody can remember why it was commented out in the first place and nobody wants to take responsibility for deleting it. Anytime I comment out code which I have reason to believe should be completely removed at some point in the future I leave a signed and dated comment as a way to mark it for permanent deletion if enough time passes. For example…
# We're removing the 'ultra-wide skyscrapper' ad to see if the new
# 'big box' unit works out better for us. If this is still commented out
# after August 1st 2012 then please delete this for good.
#
# --mluton (2012-01-11)
Finally, another benefit is that you have a unique string you can grep for. Being able to quickly find all the places where you have signed a comment can come in useful.
