PHP 程序编码规范:第5章 注释规则

2015-03-17 17:42:57 |  分类:PHP

 

5.1 一般规则

程序中要保证 20%的注释,边写程序边注释。不要吝啬注释。给以后需要理解你的代码的人们(或许就是你自己)留下信息是非常有用的。注释应该和它们所注释的代码一样是书写良好且清晰明了。偶尔的小幽默就更不错了。记得要避免冗长或者情绪化。

及时地更新注释也很重要。错误的注释会让程序更加难以阅读和理解。

让注释有意义。重点在解释那些不容易立即明白的逻辑上。不要把读者的时间浪费在阅读类似于:

i = 0; //让 i 等于 0

使用单行注释。块注释用于注释正式文档和无用代码。

把注释看成程序的一部分,在编写/维护代码时同时编写/维护注释;

注释完全采用 PHPDocumentor 的规范,以方便用其生成 API 级文档。详细规则请参见 PHPDocumentor 手册。

 

5.2 方法/函数注释

方法声明时要在开头说明其实现功能、各参数、返回值意义,复杂逻辑要在声明时说明其实现思想,并在关键步骤做出注释;

调用方法时也要指出其目的;

 

5.3 类注释

类声明时要在头部注明类作用、作者、时间;修改时要注明修改人,修改说明;类头部的注释中要列出所

有的属性、方法,并指出其意义;

 

5.4 记录所有的空语句

总是记录下 for 或者是 while 的空块语句,以便清楚的知道该段代码是漏掉了,还是故意不写的。

while ($dest++ = $src++)

; // VOID

 

5.5 用 if (0)来注释外部代码块

有时需要注释大段的测试代码,最简单的方法就是使用 if (0)块:

function example() {

great looking code

if (0) {

lots of code

}

more code

}

你不能使用/**/,因为注释内部不能包含注释,而大段的程序中可以包含注释。

 

5.6 版权信息

// +—————————————————-+

// | phpDocumentor |

// +—————————————————-+

// | Copyright (c) 2000-2003 Joshua Eichorn |

// | Email jeichorn@phpdoc.org |

// | Web http://www.phpdoc.org |

// +—————————————————-+

// | This source file is subject to PHP License |

// +—————————————————-+

备注 使用//来标示版权信息,以免和 PHPDocumentor 的 page-level DocBlock 发生冲突

 

 

 

 

 

 

2015-03-17 17:42:57 |  阅读( 0 ) |  评论( 0)
分享到: