Adding Comments to Your Scripts

I l @ ve RuBoard

Every programmer eventually figures out that making notes to yourself is a lifesaver when you inevitably need to return to a project to tweak, copy, or fix some code months later. Adding these notes, or comments, to your work helps remind you of what you were thinking at the time, which is not always so evident months later. The computer itself ignores these comments when processing the script. PHP supports three methods of adding comments.

There are two ways to comment out one line of codeby putting either // or # at the very beginning of the line you want ignored. You can also use // or # to begin a comment at the end of a PHP line like this:

 print ("Hello."); // Just a greeting. 

To comment out one line of code:

1. Open the first.php script in your text editor.

2. On line 8, before the print command, type // or # (Script 1.6).

   Script 1.6. By putting either // or # in front of a single line of code, that line will no longer be processed by the server.

   

3. Save your script, upload it to the server, and view the page in your Web browser (Figure 1.8).

   Figure 1.8. With the print command commented out, the page looks just like it would if the print command were not there. Since the server never processes the print command, the browser never receives the Hello, world! text.

   

   If it worked right, you should not be seeing anything in your browser. Don't be alarmedit's no mistake! The browser did not print "Hello, world!" because the PHP never told it to, on account of the // or # you added.

Using /* before and */ after a section of code, you can have the server ignore anything from a single word to several lines.

To comment out multiple lines of code:

1. Open the first.php script in your text editor.

2. Delete the # or // before the print() command.

3. Anywhere before the print() command on line 8 but after the initial PHP tag ( <?PHP ) on line 6, type /*.

4. Anywhere after the entire print() command on line 8 (i.e., after the semicolon) but before the closing PHP tag ( ?> ) on line 10, type */ (Script 1.6).

   Script 1.7. Although it may seem like a superfluous use of /* */ to comment out one line of code, there is nothing wrong with doing so, and we will still get the same results as if we had used // or # (Figures 1.8 and 1.9).

   

5. Save your script, upload it to the server, and view the page in your Web browser (Figure 1.9).

   Figure 1.9. It makes no difference which convention you use to comment out your script as long as you use them properly: // and # for one line and /* */ for any number of lines. (This will be the last image of absolutely nothing that I put in this book, I promise!)

   

Tip

You can comment out just one line of code (as in our example) or several using the /* and */ method. With // or # you can only ever negate one line at a time.

Tip

Different programmers prefer to comment code in different ways. The important thing is that you find a system that works for you and stick to it. Those who also do JavaScript programming will most likely use // and /* */ as these are the same in both languages. Perl programmers are more familiar with the # method.

Tip

Note that you cannot use HTML comment characters ( <! and > ) within PHP to comment out code. You could have PHP print those elements to the browser, but in that case you will be creating a comment that appears in the HTML source code on the client's computer (but not in the browser window itself). PHP comments never make it as far as a user 's computer.

Tip

As text commented out within PHP is not sent to the browser (Figure 1.10), it makes this a good place to leave notes that only the programmer will ever be able to see.

Figure 1.10. Compare the code here to that before we commented out the print command (Figure 1.7) and you'll see that the PHP code never gets to the browser. HTML code that has been commented (using <! > ) still appears in the source code but is not interpreted by the browser.

Tip

More advanced text editors such as BBEdit will use colors to indicate which code is commented out and which code is not (Figure 1.11). This can be very helpful when working on large scripts.

Figure 1.11. If your text editor color codes your code, it makes programming a lot easier. Here BBEdit puts commented code in gray, indicating that that particular code is inactive.

I l @ ve RuBoard