PHP 编码规范-注释

4.1 块注释

块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。

块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：

/*
　* 这里是块注释
*/

块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。

/*-
　* 如果想被忽略，可是使用特别格式的块注释
　*
　* one
　* 　　two
　* 　　　　three
　*/

注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)作让步。
4.2 单行注释

短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释。单行注释之前应该有一个空行。以下是一个代码中单行注释的例子：

if (condition) {

　　/* 以下代码运行的条件 */
　　...
}

4.3 尾端注释

极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。

以下是一个代码中尾端注释的例子：

if ($a == 2) {
　　return TRUE; /* 对单一条件的说明 */
} else {
　　return isPrime($a); /* 其余的条件 */
}

4.4 行末注释

注释界定符"//"，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子：

if ($foo > 1) {

　　// 第二种用法.
　　...
}
else {
　　return false; // 说明返回值的原因
}

//if ($bar > 1) {
//
// 　// 第三种用法
//　 ...
/