开头注释
所有的源文件都应该在开头有一个C语言风格的注释,其中列出类名、功能、版本信息、日期、作者和版权声明:
/*
* 类名
* 功能
* 版本
* 日期
* 作者
* 版权
*/
如果对文件进行了修改,应该在文件头中说明修改目的、修改日期、修改人,并变更文件的版本信息;如果修改问文件的一部分,则在文件中进行注释即可,并且标识出修改部分的起止位置
……
/*
* 修改目的
* 修改日期
* 修改人
* 版本
*/
……
修改起始
……
……
修改结束
……
单行注释
短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完,就该采用块注释。单行注释之前应该有一个空行。以下是一个代码中单行注释的例子:
if (condition) {
/* 以下代码运行的条件 */
…
}
尾端注释
极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中,它们应该具有相同的缩进。
以下是一个代码中尾端注释的例子:
if ($a == 2) {
return TRUE; /* 对单一条件的说明 */
} else {
return isPrime($a); /* 其余的条件 */
}
行末注释
注释界定符”//”,可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然而,它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子:
if ($foo > 1) {
// 第二种用法.
…
}
else {
return false; // 说明返回值的原因
}
//if ($bar > 1) {
//
// // 第三种用法
// …
//}
//else {
// return false;
//}
文档注释
文档注释描述php的类、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**…*/之中,一个注释对应一个类或成员。该注释应位于声明之前:
/**
* 说明这个类的一些 …
*/
class Example { …
注意顶层(top-level)的类是不缩进的,而其成员是缩进的。描述类的文档注释的第一行(/**)不需缩进;随后的文档注释每行都缩进1格(使星号纵向对齐)。成员,包括构造函数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。
若你想给出有关类、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如,有关一个类实现的细节,应放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。
文档注释不能放在一个方法或构造器的定义块中,因为程序会将位于文档注释之后的第一个声明与其相关联。