Commenting Your Scripts

The lines in a PHP web page so far have been either HTML or PHP scripts, which are meant to be read by computers. But there's also a component that's meant to be read only by peoplecomments.

Comments are annotations you add to your PHP pages to tell the story of what's going on to a human. This is important because when you come back to a long and complex script years from now, you probably won't remember what was happening in it. Or you might pass your script around for others to use. That's where comments come in. With comments, you can describe exactly how a script behaves so that you can pick it up instantly later on.

There are three types of comments in PHP. The first kind lets you write multi-line comments, beginning with /* and ending with */ like this:

 <?php /* Start by displaying a    message to the user */     echo "Hello from PHP."; ?> 

You can surround each line with /* and */ to make the comment look like a block, which will attract more attention:

 <?php /* Start by displaying a  */ /* message to the user  */     echo "Hello from PHP."; ?> 

But one thing that will make PHP choke is nesting comments inside each other, so don't do this:

 <?php /* Start by    /* displaying a */ message to the user  */     echo "Hello from PHP."; ?> 

This won't work because PHP looks for */ to end a comment, and when it sees that, it assumes the comment is endedwhich is a problem because the comment isn't actually ended, but PHP will suddenly see what it thinks is plain text where there should be PHP statements.

The other types of comments are one-line comments, designed to hold text that will fit on a single line. You can use either // to start these comments, or a #:

 <?php // Start by displaying a # message to the user     echo "Hello from PHP."; ?> 

These kinds of comments are also useful because they can be placed on lines that also contain code. In that case, PHP will ignore anything after the # or //, like this:

 <?php     echo "Hello from PHP.";        //Display a message     echo "Hello from PHP again!";  #Display another message ?> 

You can also use these comments to make blocks:

 <?php // Start by displaying a // message to the user     echo "Hello from PHP."; ?> 

Or, to make something that will really stand out, try this:

 <?php ########################## # Start by displaying a  # #/ message to the user   # ##########################     echo "Hello from PHP."; ?> 

These days, single-line comments, which are easier to write because you don't have to keep track of where they end, are prevailing. The multi-line comments still have their uses, though, and are often used at the beginning of programs to form a comment block that explains what the program is all about. They're also sometimes used when you define your own functions so that a comment-style block can indicate what the function does and how you use it.

It's a good idea to use as many comments as needed to clarify what a script is doing. Using too many comments can cloud the issue, but not using enough is worse.