Monday, July 2, 2012

7 reasons to comment your code

1. Comments remind you what you did.  However clear your code seems to you right now, some day you will look back on your code and wish you had spent the extra 5 minutes commenting your code.

2. Comments help you share your code. Code like a fine wine is meant to be shared.  What is the point of learning how to do something nobody else has ever learned and then hiding it in obscurity.  Comments add light to the obscurity of confusing code.

3. Comments organize your code.  Often times the more complex your code gets the lengthier it gets as well.  If you want to search through 1000 lines of code it is going to substantially increase your speed if you have sections and commands commented.

4. Comments are courteous.  Giving someone code or publicizing code without comments is like bringing someone into your house then turning off all of the lights.  Sure you maybe can find your way around all right but it is the very rare case that they will not spend the next few hours smacking their knees around trying to figure out where the bathroom is.

5. Comments kill bugs. As soon as your code gets sufficiently complex and you start having errors that you cannot easily track down, having comments is going to make a huge difference in figuring out where to look for bugs.

6. Comments are how the professionals do it.  If you want to make your code look good, add comments.  Code without comments is generally unintelligible without a lot of work by the reader to attempt to decipher. There is little point showcasing your code if you don't have comments.  Without comment, I don't want to read your code and nobody else wants to read it either.

7. Comments identify logical errors.  In your code if you write down everything you do then when you start getting unexpected results you will have something to look back upon and rethink.  Sometimes by writing out what you are doing then coming back to it you realize that you made assumptions that are producing misleading results.  The biggest challenge in coding is not syntactical bugs or finding the right function but identifying the structure necessary to product the results you desire.  If you have not commented your code then you are using a large portion of your mental faculties constantly translating the code in front of you rather than fruitfully spending it figuring out what you are supposed to be doing.

For specific methods of commenting in Stata see this post

1 comment:

  1. I totally agree. Commenting on codes helps specially in cases of mistakes or finding error in code. If anyone newbie is trying to understand your code then too comments are highly useful.