Commenting Your Code: Historical Evidence


There is a ton of useful blog posts and magazine articles that tells programmers to comment their code. Most people understand they should comment their code, managers try to force better comments, and people still hesitate to comment their code.

The basic idea is write down what the code does so that as other people read the code, they will easily understand what the segment of code is supposed to be doing so there is better communication, troubleshooting, and any edits to the code can be easily identified.

Some people, usually younger professionals, will minimize the importance of documentation. They will argue that their code is self-explanatory, or that good code doesn’t need very much to explain what it is doing, or if you don’t understand their code then you just aren’t a very good programmer. Even some managers will argue that you can save money by not wasting time to comment today, but risk spending extra time later if  you need to interpret the old code to make changes.

I think the best way to “sell” code comments is to have the skeptic re-write some old code. When I say old, I’m not talking about something written last year or even 5 years ago. I’m talking code that was written 10 or more years ago. Maybe the code was written in a language you are unfamiliar with, or a version of your favorite language before all the cool features were available.

Work your way through a strangers source code, and see how easily you can determine what each line of code does and why it does it the way it was written. I recently went through some code I wrote 10 years ago, and while I do write comments, I found plenty of places there could have been more comments.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s