关于php注释那些事

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

下面列下一些PHPDoc参数。

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

注释规范

a.注释必须是

/**
* 注释内容
*/

的形式

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

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

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

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

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

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

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

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

再示例

 <?php
 /**
 * Sample File 2, phpDocumentor Quickstart
 *
 * This file demonstrates the rich information that can be included in
 * in-code documentation through DocBlocks and tags.
 * @author Greg Beaver <cellog@php.net>
 * @version 1.0
 * @package sample
 */

 //PHP code

 /**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer
 */
 function firstFunc($param1, $param2 = 'optional') {
     static $staticvar = 7;
     global $_myvar;
     return $staticvar;
 }

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

     /**
      * Log the query and fire the core query event.
      *
      * @param  string  $sql
      * @param  array   $bindings
      * @param  int     $start
      * @return void
      */
     protected function log($sql, $bindings, $start)
     {
         $time = number_format((microtime(true) - $start) * 1000, 2);

         Event::fire('laravel.query', array($sql, $bindings, $time));

         static::$queries[] = compact('sql', 'bindings', 'time');
     }

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

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