As a developer, having good style is important to me. I can’t tell the number of times I’ve inherited code, and wondered what the heck was going on. I can’t tell the number of times I’ve looked at code I’ve written six months ago and wondered what the heck was going on.
In school, I was taught to comment EVERYTHING. I don’t think this was the right lesson, as we would often comment functions with self-commenting names. There is no reason to add comments to a function called "public Item GetItemById(int ID)" in my opinion.
In any case, I have made it a point to comment any code that I didn’t think had an obvious function. I also, like many people, tend to comment obsolete code instead of deleting it. This can often result in a source file in which sometimes half of the file is commented out functions. This is even harder to read than a file with no comments.
So what I’ve come up with is the Self-Expiring Comment Pattern. I think it is simple enough, and I have used it long enough, that I’m ready to see what people think of it. I’ll use JavaScript for my example:
//Todo: Delete Commented Code after 9/24/2015 or after Sprint 5
/*function oldFunction(){
}*/
//Todo: Delete comment after 9/24/2015 or after Sprint 5
//This seems to work better than oldFunction because of x, y, and z
function newFunction(){
}
The concept here is super simple. If I am looking at this code that I just inherited on week 2 of my new job, and I see these comments, I don’t even have to read them. I know they are safe to delete, and I don’t have to worry that I’m breaking anything or deleting important reference code by doing it. This is sort of a pass-the-buck approach that we are probably already aware of as developers. You would do this when you have a comment that just reflects what you are thinking about right now, but you know will not be useful once you're finished with this section of code, or when the current build is deployed. You don't have to be too accurate with the date you pick. Just pick anything that ensures that your comment will not exist until the end of life of your code.
This works even better in Visual Studio or Eclipse, which interprets Todo comments as tasks which are gathered into a Tasks pane for easy access.
Since I’ve started doing this, I have found it easier to maintain enough comments in my code to be useful, without having so much that it becomes cumbersome. I’m going to start trying to push this concept more and more in the future. It seems like a small change, but having code that’s easy-to-read is worth it I think.
I welcome thoughts and feedback on this idea.
Update: After a few conversations, I think the consensus is that this idea is a solution to a problem that has already been solved a better way. Stick with proper version control, and this idea is not necessary. Only if proper version control is not an option should this idea be considered.
Update 2: Looks like someone has previously come up with a slightly better version of my idea called Tombstones
