PHP 编码规范-注释

核心提示：块注释通常常使用于提供对文件，方法，数据结构和算法的描写。块注释被置于每个文件的开始处和每个方法之前。它们也能够被用于其他地方，比如方法内部。在功能和方法内部的块注释应当和它们所描写的代码具有1样的缩进格式。

4.1 块注释

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

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

/*
　* 这里是块注释
*/

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

/*-
　* 假设想被忽视，可是使用特别格式的块注释
　*
　* one
　* 　　two
　* 　　　　three
　*/

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

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

if (condition) {

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

4.3 尾端注释

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

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

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

4.4 行末注释

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

if ($foo > 1) {

　　// 第2种用法.
　　...
}
else {
　　return false; // 说明返回值的缘由
}

//if ($bar > 1) {
//
// 　// 第3种用法
//　 ...
//}
//else {
　　// return false;
//}
4.5 文档注释

文档注释描写php的类、构造器，方法，和字段(field)。每个文档注释都会被置于注释定界符/**...*/当中，1个注释对应1个类或成员。该注释应位于声明之前：

/**
　* 说明这个类的1些 ...
*/
class Example { ...

留意顶层(top-level)的类是不缩进的，而其成员是缩进的。描写类的文档注释的第1行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第1行缩进4格，随后每行都缩进5格。

若你想给出有关类、变量或方法的信息，而这些信息又不合适写在文档中，则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如，有关1个类实现的细节，应放进紧跟在类声明后面的实现块注释中，而不是放在文档注释中。

文档注释不能放在1个方法或构造器的定义块中，由于程序会将位于文档注释以后的第1个声明与其相干联。

评论加载中... 内容： 评论者： 验证码：