PHP | 入门篇：注释的写法

1 什么是注释？

注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。

1.1 注释的目的

注释只是为了提高可读性，不会被计算机编译。

1.1 注释的格式

注释通常会分为行注释和块注释

• 行注释: 在符号后那一行不会被编译
• 块注释: 被块注释符号中间的部分不会被编译

2 PHP 的注释格式

PHP 支持 C，C++ 和 Unix Shell 风格（Perl 风格）的注释。例如:

<?php
    echo 'This is a test'; // 这是单行 c++ 样式注释
    /* 这是一条多行注释
       另一行也是注释 */
    echo 'This is yet another test';
    echo 'One Final Test'; # 这是单行 shell 风格的注释
?>

2.1 行注释

单行注释

• C 风格单行注释

  <?php
      //这是第二行注释
      echo "http://c.biancheng.net/php/";
      // echo "PHP 注释";
  ?>
  

• shell 风格单行注释

     #这是第一行注释
      echo "C语言中文网<br>";
  

  注意：单行注释仅仅注释到行末或者当前的 PHP 代码块，视乎哪个首先出现。这意味着在 // … ?> 或者 # … ?> 之后的 HTML 代码将被显示出来：?> 跳出了 PHP 模式并返回了 HTML 模式，// 或 # 并不能影响到这一点。

  <h1>This is an <?php # echo 'simple';?> example</h1>
  <p>The header above will say 'This is an example'.</p>
  

2.2 多行注释

在需要注释的代码块上以/* 开始，以*/结束。

<?php
	/*
	    $a = "这是第一行";
	    $b = "这是第二行";
	    $c = "这是第三行";
	*/

注意：C 风格的注释在碰到第一个 */ 时结束。要确保不要嵌套 C 风格的注释。

// 错误的写法
// Error: expect statement
/*
   echo 'This is a test'; /* 这个注释会引发问题 */
*/
?>

3 小结

合理使用注释应该满足以下几项原则：

• 注释必须准确、易懂、简洁，错误的注释不但无益反而有害；
• 注释可以书写在代码中的任意位置，但是一般写在代码的开头或者结束位置；
• 修改程序代码时，一定要同时修改相关的注释，以保持代码和注释的同步；
• 在实际的代码规范中，要求注释占程序代码的 20% 左右，即 100 行程序中包含 20 行左右的注释；
• 避免在注释中使用缩写，特别是不常用缩写；
• 注释与所描述内容进行同样的缩进，可使程序排版整齐，并方便注释的阅读与理解。