文档编写和编码规范
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 {
评论1