关于php注释那些事

代码注释的作用 --- 为自己，也为别人。

永远不要过于相信自己的理解力！当你思路通畅，思如泉涌，进入编程境界，你可以很流畅的实现某个功能，但这种一泻千里的流畅可能只停留在了当时的状态。当你几个月，甚至是几个星期后看到你的代码，你可能会想，“这是哪位风骚少年堆的代码，他在干神马！？”。更不要讲更长的时间了。。

当你站在自己的代码面前尚且如此时，那么如果有和我们合作的小伙伴呢？考虑下他们的感受吧（=_=!）。

。。。所以，小伙伴们，从现在开始，请注释你的代码吧！

整理了一些网上的东西加上自己理解，供参考（这里只说php）。

php里的代码注释主要有以下三种方法：

1.以“/*"开始并且以"*/"结束的多行注释方法（当然，只要你愿意，单行也是没问题的）。

2.以 ”//"开始的单行注释。

3.以“#”开始的单行注释。

再介绍下符合PHPDoc风格的注释。好了，还是先说下PHPDoc。。。

PHPDoc的做法是在每个函数、类或变量定义前放置一个注释块。并不是所有情况下都要求如此，只是在必要的情况下才这么做。

　　每个注释块最前面是一个描述，然后是一个或多个可选的参数。例如，向一个函数增加PHPDoc注释时，可以指定输入参数和返回值数据。显然，为变量定义所编写的PHPDoc注释则包含不同的信息。

　　以下代码显示了为一个简单的用户自定义函数编写PHPDoc注释的例子：

　　首先要注意注释块如何开始。/**指示PHPDoc解析器一个PHPDoc注释已经开始。

　　注释块的第一行是一个简短的描述。一般在此只写函数、类或变量的名。

　　注释块中下一部分是一个比较长的描述。在这里大多以一种黑盒的观点描述函数、类或变量的作用。也就是说，它会做什么，而不是它怎样做。所有具体的功能或繁杂的逻辑都由代码中的标准注释来解释。

　　尽管不是必需的，不过通常的约定是在/** … */块每行起始处包含一个星号。这主要是为了提高可读性，还能容易地发现整个PHPDoc块。

　　注释块中最后一部分包含各个PHPDoc参数，解析器用这些参数来更好地链接API文档，从而为你提供实用的文档。每个参数最前面是一个@，后面紧跟着参数名，然后是该参数所需的信息。

　　这个例子中可以看到@param和@return参数。@param用于指定函数参数的各个方面：首先是参数的类型（在这里，第一个参数是一个字符串）；接下来是参数名（这里是$name）；最后是一个简短的描述，说明输入的数据应当包含哪些内容。@return参数用于提供函数所返回数据的有关信息：先指定数据的类型，然后是返回数据所包含内容的一个简短描述。

下面列下一些PHPDoc参数。

 1 <?php
 2 /**
 3 * @name 名字
 4 * @abstract 申明变量/类/方法
 5 * @access 指明这个变量、类、函数/方法的存取权限
 6 * @author 函数作者的名字和邮箱地址
 7 * @category  组织packages
 8 * @copyright 指明版权信息
 9 * @const 指明常量
10 * @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置
11 * @example 示例
12 * @exclude 指明当前的注释将不进行分析，不出现在文挡中
13 * @final 指明这是一个最终的类、方法、属性，禁止派生、修改。
14 * @global 指明在此函数中引用的全局变量
15 * @include 指明包含的文件的信息
16 * @link 定义在线连接
17 * @module 定义归属的模块信息
18 * @modulegroup 定义归属的模块组
19 * @package 定义归属的包的信息
20 * @param 定义函数或者方法的参数信息
21 * @return 定义函数或者方法的返回信息
22 * @see 定义需要参考的函数、变量，并加入相应的超级连接。
23 * @since 指明该api函数或者方法是从哪个版本开始引入的
24 * @static 指明变量、类、函数是静态的。
25 * @throws 指明此函数可能抛出的错误异常,极其发生的情况
26 * @todo 指明应该改进或没有实现的地方
27 * @var 定义说明变量/属性。
28 * @version 定义版本信息
29 */
30 function XXX($a){..}

注释规范

a.注释必须是

/**
* 注释内容
*/

的形式

b.对于引用了全局变量的函数，必须使用glboal标记。

c.对于变量，必须用var标记其类型（int,string,bool…）

d.函数必须通过param和return标记指明其参数和返回值

e.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可

f.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。

g.必要的地方使用非文档性注释，提高代码易读性。

h.描述性内容尽量简明扼要，尽可能使用短语而非句子。

i.全局变量，静态变量和常量必须用相应标记说明

再示例

 1 <?php
 2 /**
 3 * Sample File 2, phpDocumentor Quickstart
 4 *
 5 * This file demonstrates the rich information that can be included in
 6 * in-code documentation through DocBlocks and tags.
 7 * @author Greg Beaver <cellog@php.net>
 8 * @version 1.0
 9 * @package sample
10 */
11  
12 //PHP code
13  
14 /**
15 * A sample function docblock
16 * @global string document the fact that this function uses $_myvar
17 * @staticvar integer $staticvar this is actually what is returned
18 * @param string $param1 name to declare
19 * @param string $param2 value of the name
20 * @return integer
21 */
22 function firstFunc($param1, $param2 = 'optional') {
23     static $staticvar = 7;
24     global $_myvar;
25     return $staticvar;
26 }

以上列出的PHPDoc参数（如@param）比较多，并不是每个函数都要写这么多。根据环境和函数的功能不同选取合适的注释标记做注释。下面选取的laravel框架的数据库文件的log函数（方法）注释及log函数。供大家参考。

 1     /**
 2      * Log the query and fire the core query event.
 3      *
 4      * @param  string  $sql
 5      * @param  array   $bindings
 6      * @param  int     $start
 7      * @return void
 8      */
 9     protected function log($sql, $bindings, $start)
10     {
11         $time = number_format((microtime(true) - $start) * 1000, 2);
12 
13         Event::fire('laravel.query', array($sql, $bindings, $time));
14 
15         static::$queries[] = compact('sql', 'bindings', 'time');
16     }

说千道万，希望小伙伴们养成注释代码的习惯，贵在坚持。规范代码，规范注释风格。让自己更有逻辑性，更专业。共勉。

最后，以上如有错误之处，请大家指正。另有部分内容摘自网络，如有版权问题，请联系我。:-D