PHP & MySQL® Web Development All-in-One Desk Reference for Dummies®

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 ...