PHP文档编写和编码规范

霸气千秋 贡献于2011-08-04

作者 MC SYSTEM  创建于2009-05-05 02:46:00   修改者MC SYSTEM  修改于2009-05-05 04:42:00字数5460

文档摘要:文档编写是软件开发的关键一环。它提供了与如何使用程序相关的信息,还可以帮助未来的程序维护人员和程序使用者理解你在开发应用程序时所做出的决定。文档编写还有助于在未来重新查看应用程序时记起曾经做出过的设计决定。文档编写的重要性并不局限在思路的沟通上。在PHP中,文档编写还是在应用程序中包含metadata 的一种关键方法。元数据,或者说是描述数据的的数据,在不了解要访问的对象细节时,是创建对象之间高级交互行为的关键方法。它还是自我描述应用程序的一种方便的方法,并且可以自动地被解析到手册中。
关键词:

文档编写和编码规范 Kevin McArthur 文档编写是软件开发的关键一环。它提供了与如何使用程序相关的信息,还可以帮助未来的程序维护人员和程序使用者理解你在开发应用程序时所做出的决定。文档编写还有助于在未来重新查看应用程序时记起曾经做出过的设计决定。 文档编写的重要性并不局限在思路的沟通上。在PHP中,文档编写还是在应用程序中包含metadata 的一种关键方法。元数据,或者说是描述数据的的数据,在不了解要访问的对象细节时,是创建对象之间高级交互行为的关键方法。它还是自我描述应用程序的一种方便的方法,并且可以自动地被解析到手册中。 在本文中,我将解释PHP文档的一些常用格式,其中包括PHPDoc 和DocBook。正确地应用这些行业标准格式,可以创建容易阅读的代码,生成手册,并且在应用程序中嵌入元数据。值得注意的是,需要先理解本章中讲解的信息,才能使用下一章中讨论到的强大反射特性。 1 编码规范 编码规范可能会引起一些争议。很多开发人员都曾参与过一些长时间的争论,争论为什么他们的方法是最好的,而其他方法都次之。虽然关于这一话题的观点各不相同,但其中一个观点是被大家所接受的,即一致性是最重要的。正确与否取决于人的看法,但承诺是至关重要的。团队中所有成员应该遵循同样的规范并且一致地应用它们,这才是非常用要的。大多数公开的项目,如Zend和PEAR组件,都有定义得很清晰的编码标准。 这里所指的规范是非常基本的,其中大部分是用来处理大括号应该放在什么位置以及函数好变量应该如果命名的,还包括了即将讨论到的不同文档标准。 例如,一些开发人员习惯将起始的大括号与元素放字同一行上,如下: Function foo() { } 其他人则习惯将大括号放在下一行。 Function foo() { } Zend 框架和PEAR的标准都要求使用后一种形式,但是在控制结构上它们使用前一种形式。例如,在Zend框架中,会出现如下代码: If($x == 1) { $x += 50; } else if ($x == 2) { $x += 55; } else { $x = 60; } 在PEAR包中,会出现几乎一模一样的编码风格: if($x == 1) { $x += 50; } elseif ($x == 2) { $x += 55; } else { $x = 60; } 很相似,不是吗?Zend和PEAR风格上的唯一区别就是else 和if 之间否加了空格。但两者都没有遵循前面体积的函数括号标准。其他人也许会认为正确的格式应该是在任何情况下总是使用括号放在新的一行上的方法,如以下代码: if ($x == 1) { $x += 50; } elseif ($x == 2) { $x += 55; } else { $x = 60; } 哪一个是正确的?从技术角度来讲,是没有答案的。 如果试图为新的应用程序定义标准,目前为止最容易的的方法就是挑选一个项目,使用你最喜欢的标准,并且严格遵循它。 2 PHP注释和文法解析 为了最大限度地应用文档,理解不同类型注释之间的区别是非常重要的。某些类型的注释只包含提供给程序员的信息,但其他类型的注释的内容实际上是和程序数据一块儿存储的。 2.1 注释的类型 PHP 拥有几种类型的注释。 单行注释 的声明如下: // 这是一个行内注释 多行注释 的形式如下: /* 这是一个多行注释 并且可能跨多行 */ 第三种形式为 文档注释,声明如下: /** 这是文档注释,也被 称为文档块 */ 后两种形式看起来似乎很相似,但PHP会以不同的方式来解析它们。第一种形式仅仅是人类可读的信息,对PHP是没有意义的。第二种形式做了一些额外的工作,它将注释的数据和程序代码一块儿存储,这一数据可能被其他应用程序使用,用于获得关于如何与程序打交道的更多信息。下面深入探讨文档注释是如何工作的。 2.2 关于文档注释的更多信息 文档注释可以和特定的程序元素相关联,例如类、函数、常量、变量、方法等。为了将文档注释与元素相关联,只需在元素前面声明文档注释块,并确保后面的星号和斜线与元素之间没有空行即可。如下代码演示了如何将一个文档注释和函数相关联。 /** 这是一个关于函数的注释 */ function notimportant() {} /* 这不是一个文档注释,因为它不以“/**”开头 */ function notimportant() {} /** 这是一个文档注释,但却与函数无关 */ function notimportant() {} 可以看出,文档注释的要求很严格。如果没有把它们放在函数的前面,它们就不会与那个函数相关联。 现在便可以编写并关联文档注释了,但是这种关联关系实际上做了哪些工作呢?一般的注释和文档注释之间有一个关键的区别。为了理解这种区别,需要了解PHP解析过程运行机制的一些背景知识。 2.3 文法解析 虽然PHP表示一种编译语言,但是它和编译语言很类似,因为PHP代码在被实际执行之前会被转换成二进制格式。 这种从编程语言到可执行代码的转换过程被称为文法解析,这是因为它将PHP代码的文法结构转换成操作码(PHP语言元素的数字形式的表示)。当文法解析器遇到一个正常的注释时,它会识别它并且忽略它,并且会废掉注释中的所有数据。所有被废气的数据不再出现在最终的二进制格式中,并且不能被其他程序访问,因此一般的注释是无法嵌入元数据的。 另一方面,和函数或类相似,文档注释是会被实际解析的,并且它的数据会被存储。它会成为二进制数据的一部分,而且更重要的是,当文档注释和代码元素一起声明时,它会与那个元素相关联。这种关联对于创建数据的场景是至关重要的。 注释的场景是非常重要的,这是因为元数据是通过向程序询问元素细节并检查相关联的文档注释属性的方式来访问它。没有这种关联关系,就不能以编程的方式来使用文档注释,只能把它作为一个正常的多行注释来使用。 文档注释和编程元素的关联提供了在程序中嵌入附加元数据的功能。 2.4 元数据 元数据是描述其他数据的数据。在编程术语中,这意味着元数据是关于程序的信息。例如,类中所有方法的名称就可以被当作元数据。 默认情况下,PHP包含了大多数编程元素的元数据。然而,你可能需要嵌入比PHP正常产生的元数据更多的元数据。比方说,一些系统使用元数据属性来包含测试信息,例如对于特定输入所期望的输出结果。 其他一些语言直接附加元数据的添加,它们是通过一种叫做特性的编程元素来添加的,但是PHP没有包含这种功能。然而,这种功能可以通过对文档注释的解析来模拟。例如,可以嵌入对应用程序执行不重要但对创建代码的手册却很重要的元数据。 以这种方式使用元数据在自动生成文档方面非常有用。从元数据创建手册的其中一种方法就是使用PHPDoc标准。如果创建遵循特定格式的文档注释,解析器程序可以将注释自动转换为有意义的文档。 3 PHPDoc PHPDoc(http://www.phpdoc.org)是用于维护PHP文档的一种最为广泛的解决方案。如果使用过PEAR库或者任何类型的预打包PHP库,那么一定已经碰到过PHPDoc了。 PHPDoc为文档注释定义了一种结构,允许解析器以一种一致的方式解析它们。PHPDoc与文档注释的关系正如HTML与XML的关系一样。有了PHPDoc,就可以从嵌入文档中创建有用的手册了。 PHPDoc包含了如何声明文档注释的一套规则,这些规则几乎本身就是一种语言。PHPDoc块可以定义十几种不同的元数据。这里,只介绍PHPDoc基本的最常用的部分。 和所有文档注释一样,PHPDoc块必须以/**注释声明开始。然后是与正在描述的项相关的正常描述信息。 /** 这里是PHPDoc注释,用以描述somefunction函数 */ function somefunction() {} 这遵循了所有文档注释的格式,特殊之处在于标签。标签是由 @ 符号加上一个预定义的标识符表示的。它们可以出现在一行的开头,或者出现在注释中的任何地方,但是要放在大括号里面。支持的标识符是预定义的,它们形成了文档解析器如何解释注释的规则。 /** 这里是PHPDoc注释。 @param bool $foo Foo 给函数传递了一些信息 */ function bar($foo) {} 值得注意的是,@param 标签描述了函数的 $foo 参数。这是元数据,可以稍后被解析器阅读,从而数据关于 $foo 的文档。标签的格式允许添加一些附加的元数据,例如变量的类型、变量的名称以及对操作的描述。所有的PHPDoc标签都遵循这一基本格式。 @param 标签只是大量标签中的一个。下面列出了应用于PHP5以及之后版本的最常用的一些PHPDoc标签。要查看完整的标签列表,可参见 http://manual.phpdoc.org/ 。 标签 说明 @access public|private|protected 描述了访问级别。当使用反射技术时,这个标签不是很有用,这是因为API能够自动获取这一特性。在PHPDoc中,用它可略去私有成员的文档生成 @author Author Name [] 帮助获得负责某个特定元素的人的信息(强烈推荐使用这一标签) @copyright Copyright Information 可指定代码的版权所有者 @deprecated [version information] 可通知代码的使用者这个元素不再被使用并且已经被替换 @exmple [path|url] description 可引用一个例子,阐释如何使用这个元素。第二个参数可以是一个路径也可以是一个完整的URL @filessource 可用来表示希望让文件源出现在文档中。这一标签只能出现在页面级别的块中,在其他地方出现将会被忽略 @globale datatype description 说明了全局变量的数据类型。这一标签必须紧贴在全局变量的前面,并且只对phpDocumentor解析器起作用。对于基于反射技术的解析器用处不大 @ignore 通知解析器忽略这个元素,并且不将它包含在文档中 @internal 可以隐藏特定的信息,使之不出现在公开文档中。可以用在内嵌的注释内容中或者新行注释中 @lincense url [lincense] url 指定此软件授权信息的URL,还可以说明授权者的姓名 @link url [description] url 在文档中包含一个连接。这个标签可以用在内嵌的内容中 @param datatype $variablename[, …] description 说明函数和方法关联的参数。这可能是最重要的标签。变量名称参数可以包括,…符号以表示函数可以传入不定量的其他参数 @return datatype description 说明了函数或方法返回的数据类型。这可能是第二个重要的标签,并且它是在PHP中包含关于返回数据的元数据的唯一方法。推荐所有具有返回值的函数使用这一标签 @see reference 引用另外一个元素的文档。在这里可以使用不同类型的指针,包括文件、函数名称、类方法以及其他许多类型的指针。多个指针值可以用逗号隔开。这个标签也可以用在内嵌的内容中 @since version [information] 用于说明这个元素第一次出现的版本信息 @source startoffset [endoffset] 用于包括内嵌于文档中的相关联元素的部分源代码内容。 @todo description 包含了待完成工作的信息,或者待解决问题的信息。 @var datatype 说明了类变量的类型,类变量也被看作是属性 @version 指定了元素的当前版本号 下面的代码演示了一个函数上的一些典型的PHPDoc注释。 /** * 这个函数连接了两个字符串 * * 通过获得第一个字符串,并将它添加到第二个字符串上,最后返回结果, * 它完成了这一功能 * @param string $string1 左边的字符串 * @param string $string2 右边的字符串 * @return string A 包含了合并后内容的字符串 * @todo 添加一个连接字符参数 */ Function concatTwoStrings($string1, $string2) { return $string1 . $string2; } 现在已经编写了所有的文档块和标签,那么如果使用它们来创建手册呢?其中一方法是使用phpDocumentor解析器,也可以使用反射技术来解析这些信息。现在将介绍如何使用phpDocumentor。获得phpDocumentro解析器工具最简单的方法是从PEAR包中安装它。 pear install PhpDocumentor 这样就可以使用phpdoc命令了。首先可以尝试一下以下命令。 phpdoc –f somefile.php –t /path/to/output/directory 建议将输出路径指定为Web根目录,这样就可以从Web浏览器中查看输出结果了。Phpdoc命令提供了大量的输出选项,以下为其中部分选项: l HTML:frames:default, 输出为HTML桢格式; l HTML:Smarty:default, 输出为Smarty模板格式; l CHM:default:default, 输出为Windows帮助文件格式; l PDF:default:default, 输出为PDF格式。 使用以下命令格式添加 –o 选项就可以指定这些输出选项了。 output:converter:templatedir 使用 –h 选项可以显示所有的选项和参数。 在phpdoc命令运行后,将会在输出目录中出现一个HTML文件。可以使用Web浏览器查看这个文件,其中包含了PHP文件中的代码信息。

下载文档到电脑,查找使用更方便

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 20 金币 [ 分享文档获得金币 ] 0 人已下载

下载文档