关于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
