PHP中类和文件的代码注释规范

编写好的文档对于任何软件项目都至关重要,不仅是因为文档的质量可能比代码的质量更重要，还因为良好的第一印象会促使开发人员进一步查看代码以及后续的迭代。

文件注释

/**
 * Sample file comment
 *
 * PHP version 7.1.0
 * 
 * This file demonstrates the rich information that can be included in
 * in-code documentation through DocBlocks and tags.
 * @author Greg Sherwood <something@email.com>
 * @version 1.0
 * @package PHP_CodeSniffer
 */
复制代码

1. 简介或名称。
2. 当前使用PHP版本。
3. 当前文件的详细介绍。
4. @author 作者，语法：@author name <email>。此标记可以用来标记任何可以记录的元素（包括但不限于全局变量，变量，引入，常量，方法，类，页面等）。
5. @version 版本，语法：@version ["Semantic Version"] [description]。同样可以记录所有元素的版本。
6. @package 包，语法：@package [level 1]\[level 2]\[etc.]。用于将相关的页面或类进行逻辑分组。

类注释

/**
 * Sample class comment
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Greg Sherwood <something@email.com>
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class Missing_Newlines_Before_Tags
{
}//end class
复制代码

1. 简介或名称。
2. @category 分类，该标记用于将多个包package组合在一起。
3. @package 包，用于逻辑分组。
4. @author 作者,语法：@author name <email>。
5. @license 许可证，语法：@license [<SPDX identifier>|URI] [name],该标记向用户提供许可信息，第一个参数是由SPDX开源许可证注册机构定义的“SPDX标识符” ，或者是包含完整许可证文本的文档的URL.第二个参数可以是适用许可证的正式名称，文中的BSD Licence是开源界的五大许可协议之一。在写开源项目的时候选择一个适合的开源License尤为重要，许可的目的是，向使用你产品的人提供一定的权限。
6. @link 链接,语法：@link [URI] [description],标记指示关联的“结构元素”和网站之间的自定义关系，该关系由绝对URI标识。他也可以用于链接到其它方法，例：@link MyClass,不过一般来说，如果您想链接到元素的文档，请使用@see或inline {@link}可能会是一个更好的选择。

方法注释

/**
 * Return a thingie based on $paramie
 * @param boolean $paramie 
 * @return integer|babyclass
 */
function parentfunc($paramie)
{
    if ($paramie) {
        return 6;
    } else {
        return new babyclass;
    }
}
复制代码

1. 简介或名称。
2. @param 参数,语法：@param ["Type"] [name] [<description>],标签用于记录函数或方法的单个参数,且可以有多行描述，不需要明确的分隔。
3. @return 返回，语法：@return <"Type"> [description],标签用于记录函数或方法的返回类型，同样支持多行描述。

变量注释

/**
 * Configuration values
 * @var array $thirdvar
 */
var $thirdvar;
复制代码

1. 变量描述。
2. @var 变量，语法:@var ["Type"] [element_name] [<description>]，标签用于记录变量类型，也用于记录常量等

值得说明的是，@category和@link这两个标记在新发布的PSR-5PHP文档标准中被标注为已废弃[deprecated]，可正常使用，但不推荐使用，文档能正常生成。

后记

这样写出来生成的代码注释，也方便后期维护，而且PSR-5出了关于代码文档的规范，通过使用phpDocumentor还能生成自己的软件项目文档，他还提供生成不同受众显示不同文档内容，很是方便，上面的模板只是简单的介绍几个场景下经常用到的Tag，实际情况请选择使用适合的标签，形成自己项目的代码注释规范。更多可查看官方的介绍。

好的注释也是让别人了解你代码思想的一部分，向写注释的程序员致敬！(￣^￣)ゞ

共勉~