构建知识体系之二--PHP注释风格

碰到神一般的境界：写代码的时候，只有上帝和他知道代码是什么意思，现在只有上帝知道了。

team work中经常的交流不是在讨论问题，而是重构别人的代码，之前有个任务真的是把我恶心到了，有大量复杂的逻辑代码，木有注释，看着大量的switch case，if else，再看看代码量，上了800行的函数就有六个，我死的心都有了。

从我重构完代码，我就发誓，造福后来者，写代码规范，有标准的注释，函数不会在30秒内看不懂，有完整的测试用例，或者是demo。

先来给个简单的注释：

/**
 * @author          water(作者)
 * @example         /path/to/example(可以是实例demo或者是测试文档也行，有了这个其他程序员使用的时候，运行一下就知道参数和返回值了)
 * @param           参数，可能有好几个
 * @return          返回值
 * @throws          方法抛出的异常
 * @since           记录什么时候对文档的哪些部分进行了更改(更改日志)
 */

要是想更少点，成员函数中的注释就不需要这么多了

/**
 * @author          water(作者)
 * @example         /path/to/example(可以是实例demo或者是测试文档也行，有了这个其他程序员使用的时候，运行一下就知道参数和返回值了)
 * @param           参数，可能有好几个
 * @return          返回值
 */

额，好像还少了一个brief：函数简介。总之就一句话，函数写成一个黑盒子，看看注释就能懂能用

例子请看这里：PHP字符编码

小技巧：

不能只是为了这个注释浪费很多时间？要效率？看这里：

 如果嫌每次写这个注释麻烦（我当时就是），可以把这个copy一份模板放到常用代码中，使用的时候直接copy。

另外，更简单的办法就是更改zend studio或者eclipse中的模板，让强大的IDE自动生成模板。

但是，里面的比如参数，返回值，测试demo等，就必须由自己来改好了，木有这么自动的

如果不会IDE自动生成模板的方法。哼！要度娘作甚！

下面是PHP的注释标准：不为别的，这个是PHPDOC的标准，写好了注释，也就写好了API文档：

PHPDocumentor是一个用PHP写的工具，对于有规范注释的php程序，它能够快速生成具有相互参照,索引等功能的API文档

标记	用途	描述
@abstract		抽象类的变量和方法
@access	public, private or protected	文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author	张三 <zhangsan@163.com>	文档作者
@copyright	名称 时间	文档版权信息
@deprecated	version	文档中被废除的方法
@deprec		同 @deprecated
@example	/path/to/example	文档的外部保存的示例文件的位置。
@exception		文档中方法抛出的异常，也可参照 @throws.
@global	类型：$globalvarname	文档中的全局变量及有关的方法和函数
@ignore		忽略文档中指定的关键字
@internal		开发团队内部信息
@link	URL	类似于license 但还可以通过link找到文档中的更多个详细的信息
@name	变量别名	为某个变量指定别名
@magic		phpdoc.de compatibility
@package	封装包的名称	一组相关类、函数封装的包名称
@param	如 [$username] 用户名	变量含义注释
@return	如 返回bool	函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see	如 Class Login（）	文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since	version	记录什么时候对文档的哪些部分进行了更改
@static		记录静态类、方法
@staticvar		在类、函数中使用的静态变量
@subpackage		子版本
@throws		某一方法抛出的异常
@todo		表示文件未完成或者要完善的地方
@var	type	文档中的变量及其类型
@version		文档、类、函数的版本信息