Appropriately Commenting Your Code - Practices

Comments are a programmer's way of translating code into English, especially code that may not be directly intuitive. Comments seem to be a religious issue to some, often fought over with fierce potency and leading to lengthy debates. I happen to be in favor of comments, because good comments add transparency to the code and makes the job of reviews easier.

Comments explain your syntax. They explain particularly lengthy or difficult to read code segments and can also be used to provide the programmer with reminder messages about why he or she chose to code the loop this way instead of that way. They also serve as markers in the code, which are generally taken out later in life. Markers help the programmer remember where to put code, or to remind the programmer of incomplete code fragments.

Remember that if comments are not useful, they can create more of a burden than benefit. Creating effective comments is a skill, just like mastering programming syntax. First, let's take a look at how to comment your code well.

In the following examples, we use PHP's comment syntax. A one line PHP comment is always preceded with double slashes (//). Let's take a look at a poor comment.

// loop from 0 to 50 
for ($x=0;$x<=50;$x++) 
{ 
echo States[$x]; 
$Inc .= $Incrementor; 
if (($Inc == 9) || ($Inc == 10)) 
{ 
echo "
Execute this line of code"; 
} 
} 

Is the above comment accurate? Yes, I suppose it is. But, does it add anything to the code? No, not really. It states the obvious, that we are looping through 0 to 50. To make comments effective, be sure they are descriptive enough; ensure comments earn their keep. Let's re-write the above comment snippet, using a better comment.

// print out all 50 states, including an 
// extra line for states 9 and 10 
for ($x=0;$x<=50;$x++) 
{ 
echo States[$x]; 
$Inc .= $Incrementor; 
if (($Inc == 9) || ($Inc == 10)) 
{ 
echo "
Execute this line of code"; 
} 
} 

Now we have a pretty good idea about what this loop does. Not only do we specify what this loop's purpose in life is, we also touched on the purpose of the if statement inside the loop. Of course in this case, the if statement is little more than useless. In a real application, that if statement would provide extra functionality or logic and should be described in the comment more fully.

One method to fill your source code effectively with comments is to describe your entire page first with English, avoiding any syntax what-so-ever. Once the page is described in English, cut and paste your description, comment it (ie: //), and write the code to satisfy that comment underneath it. Although this method takes longer, it certainly does ensure your code is sufficiently commented.

Let's move on now to generalized comments, often describing the entire source code page. Many developers devote a few lines at the top of their source code to provide information like function name/source code page name, programmer's name, date authored and a description of the contained functionality.

Here is a clear, efficient comment block that provides these details (remembering that /* and */ signify multiline comments in PHP).

/* ---------------------------------------------- 
Page: DBLogin.php 
Date: 10/31/03 
Author: Bill Simon 
Page controls database login details to 
connect to the MySQL database. 
-----------------------------------------------*/ 

This comment block is clean, clear and under control, would you say? It is easy to see that these comments belong together because they are boxed in above and below, and provides pithy, yet detailed, page information.

In general, do not comment simple lines of code, like variable declarations for example. You may comment an entire block of variable declarations above it, but not each individual line within the block. Use comments that provide additional information for the code and explain logic not intuitively obvious from the syntax. Overly commented code adds nothing but size to the application.

For example, the following is an example of grossly overused comments, because each variable declaration is quite intuitive.

$strName = "Steve" // declare $strName as Steve 
$strPhone = "888-888-8888" // declare $strPhone as 888-888-8888 
$strCity = "Scottsdale" // declare $strCity as Scottsdale 

Commenting the entire variable block, however, is appropriate.

// declare and assign personal variables 
$strName = "Steve" 
$strPhone = "888-888-8888" 
$strCity = "Scottsdale" 

Notice that in each example, the comment precedes the code (for the exception of the overused comment example, which is the exception). Remember to place all comments before the code, so the code reader knows what to expect, except in the event of commenting non-intuitive variable declarations, where comments can safely be placed on the same line as the code.

To wrap up, here's what you should have learned:

• Comments serve as explanations or reminders (markers)
• Write comments that describe complex code
• Except for one line variable declarations, comments precede code
• Possible technique: English first, code second
• Overused comments add nothing but size to the application
  Next: Unit Testing >>
  
  
  

  >>> More Practices Articles          >>> More By Steve Adcock

  
  
  blog comments powered by Disqus