Beautiful code calls for beautiful comments

22Nov08

I am a programmer. However, I am also a lover of any language – be it computers, foreign, or even my own. Therefore, I like to read, I love to learn, and I love to understand. One of the areas in my life that this applies to is creating beautiful code. And of course, as important as the code itself lies the commenting of the code. What happens years from now when you quit your job, someone else comes in, and they cannot understand the purpose of a certain parameter, argument, or function ? Or worse, what happens when two weeks from now you cannot understand the reason why a certain block of code is there OR what the function of it really is? Alas, the code has to be re-written, or taken a part piece by piece and possibly renamed.

Of course, naming variables and function names properly will help with much of the distress, however comments created in plain English helps a lot as well.

Many of the reasons I comment the way that I do comes from the PEAR coding standards for header comment blocks. I have also been to numerous web pages, and read many different books about programming. Lots of people have different ways of doing this, but this is my preference. I would be interested in hearing what you do OR what you would change about my commenting philosophies.

General places I add multi-line comments:

• Top of all pages
• Top of include files
• Top of javascript and CSS files
• Beginning of loops

General places I add single-line comments:

• End of loop – inline comment

This is not to say that comments should always be in these places. Use comments with some common sense! Place comments at the beginning of long blocks, not on every line of your code. Make your page easy to understand, not overly complicated due to trying to make it understandable. Comment code where the reason for the block of code is not instantly clear. Finally, if you are already using good naming practices for your functions and variables, your code should be pretty understandable with one good definition.

Comments that I usually add:

• Description* : If describing a function, it should describe why the function works, and not how. The how is visible, but the reason as to why you did it is not. What was your reason for this function? Are there any reasons that you did it this way? Is there a gotcha you found along the way when developing, and that is why you created it like this? Did it take you a while to figure this out? Is this a cross-reference to somewhere else? Did you *borrow* some of this code from somewhere? Is there somewhere that explains why you did what you did a certain way?
  Which is better:
  • Loops over the iterator variable fifty times and adds the value to the array.
  • Creates colors array to be used with the animals class.
• Creator*
• Date created*
• What is returned and returned data type
• Any parameters, parameter data type, and short definition if necessary
• Page calling (if include)
• Dependencies
• TODO
• Change log (only for major changes (example below is not major!))
  • Change date
  • Change by initials
  • Change description

*always included

Javascript example:

/**
* Validates a string
* Author : CodeStar
* Called from: index.php
* @return boolean
* @param string myString:: String entered into input field
* @todo :: remove un-needed variable
* Changelog:
* 10/10/2008 C.S. :: Renamed inner loop from 'i' to 'valIndex'
*/

A few comment tags:

• HTML: <!– comment text –>
• CSS: /* comment text */
• C#, C++, CFScript, Javascript & PHP: //for single || /* multi-line comment */ for multiple
• CFML : <!— multi-line comment —>
• SQL server: — (two dashes) for single || /* multi-line comment */ for multiple
• MySQL: — (two dashes) OR # for single || /* multi-line comment */ for multiple
• Pear, .htaccess : #

*Final tip* – Comment as you go or at the beginning. Don’t wait until the very end… you may not do it, forget about it, and then later have problems!

Filed under: Beginner   |  Leave a Comment