小左闲谈

PHP语言的多种标准注释方法

当前位置:首页 » 学习 » 本页
In 学习  @2012-07-24

PHP 注释 (Comments) 有两种类型,一种是单行注释,一种是多行注释。

PHP 单行注释语法
在一行中所有 // 符号右面的文本都被视为注释, 因为 PHP 解析器忽略该行 // 右面的所有内容。
示例如下,是单行注释的内容。



你也可以这样写,一行只写注释,不写代码,如下:

PHP 多行注释语法
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) {
//
//  // 第三种用法
//  …
//}
//else {
// return false;
//}

4.5 文档注释

文档注释描述php的类、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**…*/之中,一个注释对应一个类或成员。该注释应位于声明之前:

/**
* 说明这个类的一些 …
*/
class Example { …

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

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

文档注释不能放在一个方法或构造器的定义块中,因为程序会将位于文档注释之后的第一个声明与其相关联。

本文为网络转载,原始出处不详,如有招领,请留言!:)

若无特殊声明,表示本文由:小左闲谈.原创
链接地址: http://blog.m1910.com/archives/211.html
版权所有 © 转载时请以链接形式注明作者和原始出处!
标签: ,   评论: 抢沙发  被围观 2,258 次

发表一下你的看法

您将是第一位评论人!

avatar
wpDiscuz