1.3 编写注释

创建可执行的PHP代码只是编程过程的一部分(诚然,它是最重要的部分)。动态Web站点开发的一个次要但仍然至关重要的工作是为你的代码加注释。实际上,当被问及新手程序员与老头的区别时,我的回答始终是能否写出好的、详尽的注释。

在HTML中,可以使用特殊标签添加注释:

<!-- Comment goes here. -->

HTML注释在源文件中可以看到,但是不会出现在呈现的页面中(参见图1-7和图1-8)。

PHP注释则有所不同,因为它们根本不会被发送到Web浏览器,这意味着最终用户不会看到它们,即使查看HTML源文件也是如此。

PHP支持3种注释类型。第一种使用磅即编号符号(#)。

# This is a comment.

第二种使用两个斜杠。

// This is also a comment.

这两种注释都会使PHP忽略其后直到行末(当你按Return或Enter键时)的一切内容。因此,这两种注释都只是单行注释。它们还常用于在PHP代码行内添加注释。

print 'Hello!'; // Say hello.

第三种风格允许注释分布在多行上。

/* This is a longer comment
that spans two lines. */

给脚本加注释

1. 在文本编辑器或IDE中新建一个PHP文档,命名为comments.php(参见脚本1-4)。

1    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3    <head>
4       <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5       <title>Comments</title>
6    </head>
7    <body>
8    <?php
9    
10   # Script 1.4 - comments.php
11   # Created March 16, 2011
12   # Created by Larry E. Ullman
13   # This script does nothing much.
14   
15   echo '<p>This is a line of text.<br /> This is another line of text.</p>';
16   
17   /*
18   echo 'This line will not be executed.';
19   */
20   
21   echo "<p>Now I'm done.</p>"; // End of PHP code.
22   
23   ?>
24   </body>
25   </html>

2. 添加初始PHP标签,并且编写你的第一条注释。

<?php
# Script 1.4 - comments.php
# Created March 16, 2011
# Created by Larry E. Ullman
# This script does nothing much.

每个脚本都应该包含的最初几条注释之一是一个介绍性的块,其中列出了创建日期、修改日期、创建者、创建者的联系信息、脚本的目的,等等。有些人认为shell风格的注释(#)在脚本中更醒目,因此这种注释是最佳的。

3. 将一些HTML代码发送到Web浏览器。

echo '<p>This is a line of ?text.<br />This is another line ?of text.</p>';

它与你在这里做什么无关,而只是让Web浏览器显示一些内容。出于改变显示内容的目的,我使用echo()语句打印一些HTML标签,包括换行符(<br/>),在生成的HTML页面中添加一些间距。

4. 使用多行注释来注释掉第二条echo语句。

/*
echo 'This line will not be executed.';
*/

/**/来包围任何PHP代码块,可以使代码不起作用,而不必将其从脚本中删除。之后可通过删除注释标签,重新激活那部分PHP代码。

5. 在最后一条echo语句后面添加最后一条注释。

echo "<p>Now I'm done.</p>"; ?// End of PHP code.

这条最后的(有些多余的)注释说明了如何把一条注释放在一行的末尾,这是一种常见的惯例。注意:我使用双引号包围消息,因为单引号会与撇号冲突(参见本章前面的框注“需要转义”)。

6. 关闭PHP部分并完成HTML页面。

?>
</body>
</html>

7. 将该文件另存为comments.php,存放到Web目录中,然后在Web浏览器中测试它(参见图1-9)。

图1-9 脚本1-4中的PHP注释不会出现在Web页面或HTML源文件中(参见图1-10)

8. 有好奇心的读者可以在Web浏览器中检查源代码,确认没有出现PHP注释(参见图1-10)。

图1-10 在客户端浏览器中查看脚本1-4中的PHP注释

提示

  • 不应该嵌套多行注释(/* */)(把一条注释放在另一条注释内),因为这会引起问题。

  • 在行末(比如,在函数调用后面)可以使用任何PHP注释:

    echo 'Howdy'; /* Say 'Howdy' */
    

尽管也可以用/**/,但一般不这样做。

  • 对脚本进行注释几乎可以说是多多益善。话虽如此,为了节省篇幅,本书中的脚本并没有按我建议的那样加足够的注释。

  • 在修改脚本时保持注释是最新的和准确的也很重要。没有什么比注释说的是一套,而代码实际上做的是另一套更让人迷糊的了。

目录