文档编写和编码规范 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 关于文档注释的更多信息
文档注释可以和特定的程序元素相关联,例如类、函数、常量、变量、方法等。为了将 文档注释与元素相关联, 只需在元素前面声明文档注释块, 并确保后面的星