1.12. Adding Comments to Your PHP Script

Comments are notes embedded in the script itself. Adding comments in your scripts that describe their purpose and what they do is essential. It's important for the lottery factor — that is, if you win the lottery and run off to a life of luxury on the French Riviera, someone else will have to finish the application. The new person needs to know what your script is supposed to do and how it does its job. Actually, comments benefit you as well. You might need to revise the script next year when the details are long buried in your mind under more recent projects.

Use comments liberally. PHP ignores comments; comments are for humans. You can embed comments in your script anywhere as long as you tell PHP that they are comments. The format for comments is

/*  comment text
more comment text  */

Your comments can be as long or as short as you need. When PHP sees code that indicates the start of a comment (/*), it ignores everything until it sees the code that indicates the end of a comment (*/).

One possible format for comments at the start of each script is as follows:

/*  name:        catalog.php
 *  description: Script that displays descriptions of
 *               products. The descriptions are stored
 *               in a database. The product descriptions
 *               are selected from the database based on
 *               the category the user entered into a form.
 *  written by:  Lola Designer
 *  created:     2/1/06
 *  modified:    3/15/06
*/

You should use comments throughout the script to describe what the script does. Comments are particularly important when the script statements are complicated. Use comments such as the following frequently:

/* Get the information from the database */
/* Check whether the customer is over 18 years old */
/* Add shipping charges to the order total */

PHP also has a short comment format. You can specify that a single line is a comment by using the pound sign (#) or two forward slashes (//) in the following manner:

# This is comment line 1
// This is comment line 2

All text from the # or // to the end of the line is a comment. You can also use # or // in the middle of a line to signal the beginning of a comment. PHP will ignore everything from the # or // to the end of the line. This is useful for commenting a particular statement, as in the following example:

$average = $orderTotal/$nItems;  // compute average price

Sometimes you want to emphasize a comment. The following format makes a comment very noticeable:

######################################
##  Double-Check This Section       ##
######################################

PHP comments aren't included in the HTML code that is sent to the user's browser. The user does not see these comments.

Use comments as often as necessary in the script to make it clear. However, using too many comments is a mistake. Don't comment every line or everything you do in the script. If your script is too full of comments, the important comments can get lost in the maze. Use comments to label sections and to explain unusual or complicated code — not obvious code.