| Writing the executed PHP code itself is only a part of the programming process. A secondary but still crucial aspect to dynamic Web site development involves documenting your code. In HTML you can add comments using <!-- Comment goes here. -->
HTML comments are viewable in the source (Figure 1.11) but do not appear in the rendered page. Figure 1.11. HTML comments appear in the source code but not in the Web page itself. 
PHP comments are different in that they aren't sent to the Web browser at all, meaning they won't be viewable to the end user, even when looking at the HTML source. PHP supports three comment types. The first uses the pound or number symbol (#). # This is a comment.
The second uses two backslashes. // This is also a comment.
Both of these cause PHP to ignore everything that follows until the end of the line (when you press Return or Enter). Thus, these two comments are for single lines only. They are also commonly used to add a comment on the same line as some PHP code. print 'Hello!'; // Say hello.
A third style allows comments to run over multiple lines. /* This is a longer comment that spans two lines. */
To comment your scripts 1. | Open whitespace.php (refer to Script 1.4) in your text editor.
| 2. | After the initial PHP tag, write your first comment (Script 1.5).
# Created February 2, 2005 # Created by Larry E. Ullman # This script does nothing much.
Script 1.5. These basic comments demonstrate the three syntaxes you can use in PHP. 
One of the first comments each script should contain is an introductory block that lists creation date, modification date, creator, creator's contact information, purpose of the script, and so on. Some people suggest that the shell-style comments (#) stand out more in a script and are therefore best for this kind of notation.
| 3. | Use the multiline comments to comment out the second echo() statement.
/* echo "<br />This line should appear  separately in the Web page.\n\n; */
By surrounding any block of PHP code with /* and */, you can render that code inert without having to delete it from your script. By later removing the comment tags, you can reactivate that section of PHP code.
| 4. | Add a final comment after the last echo() statement.
echo 'Now I\'m done.'; //  End of PHP code.
This last (superfluous) comment shows how to place one at the end of a line, a common practice.
| 5. | If you want, change the HTML page's title.
| 6. | Save the file as comments.php, upload to your Web server, and test in your Web browser (Figure 1.12).
Figure 1.12. The PHP comments in Script 1.5 don't appear in the Web page, but they did have the effect of omitting a sentence (compare with Figure 1.9). 
|
 Tips
You shouldn't nest (place one comment within another) multiline comments (/* */), as it will cause problems. Any of the PHP comments can be used at the end of a line (say, after a function call): echo 'Howdy.'; /* Say 'Howdy' */
Although this is allowed, it's far less common. It's nearly impossible to over-comment your scripts. Always err on the side of writing too many comments as you code. That being said, in the interest of saving space, the scripts in this book will not be as commented as I would suggest they should be.
|
