首页 技术文章 php

php代码注释规范

发布日期: 2024-04-21
FontSize: 【小 中 大】
php代码注释规范

php注释有很多种方法，我们可能总是很随性，很少去思考注释的规范性，一般只是自己看得懂就行，有的甚至没有写注释。有时候可能，回头再看自己写的代码，已经不记得它是干什么用的了。又或者是，公司的开发人员离职了，新的开发人员看不懂以前的class与function的功能是什么，这时候，注释就变得相当重要，如果注释写的很规范，可以生成一份说明文档。

phpdoc注释规范可以详见https://docs.phpdoc.org。

php注释示例：

<?php
// 这是一行注释

/* 这是一行注释 */

/* 
这是一行注释
*/

注意，使用//注释，后面的内容不可以换行，而/**/包含的注释，可以随意换行。

虽然上面的代码达到了注释的效果，但并不规范。

PHPDoc关于php代码编写文档的标准注释格式

<?php
/**
 * 这里是注释的简要描述。
 *
 * 这里是注释的详细描述，可以包含更多信息和说明。
 *
 * @标签名称 标签值
 * @标签名称 标签值
 * ...
 */

注释以 /** 开始和 */ 结束，描述部分包括简要描述和详细描述。标签部分由 @ 符号开始，后面跟着标签名称和标签值。

标准注释格式示例：

<?php
/**
 * Class a
 * @author    A Little Duck <duck@lichil.com>
 * @license   http://opensource.org/licenses/gpl-license.php GNU Public License
 * @copyright A Little Duck
 */
class a {


    /**
     * Class version
     *
     * @access public
     * @var string
     */
    var $version;
	
	/**
     * 裁剪图像
     *
     * 这些值可以在数组中，也可以在空格分隔的字符串中。
     * 每个值可以是像素（带或不带“px”）或百分比（源图像）
     *
     * 例如，有效的参数是
     * <pre>
     * $a->image_crop = 20                  OR array(20);
     * $a->image_crop = '20px'              OR array('20px');
     * $a->image_crop = '20 40'             OR array('20', 40);
     * $a->image_crop = '-20 25%'           OR array(-20, '25%');
     * $a->image_crop = '20px 25%'          OR array('20px', '25%');
     * $a->image_crop = '20% 25%'           OR array('20%', '25%');
     * $a->image_crop = '20% 25% 10% 30%'   OR array('20%', '25%', '10%', '30%');
     * $a->image_crop = '20px 25px 2px 2px' OR array('20px', '25%px', '2px', '2px');
     * $a->image_crop = '20 25% 40px 10%'   OR array(20, '25%', '40px', '10%');
     * </pre>
     *
     * 默认值为null（无裁剪）
     *
     * @access public
     * @var string OR array;
     */
    var $image_crop;
	
	/**
     * 解码颜色
     *
     * @access private
     * @param  string  $color  Color string
     * @return array RGB colors
     */
    function getcolors($color) {
		//执行内容
	}
}

示例代码中，关于属性（变量）$image_crop的说明非常详细到位，列举了所有可以出现的格式。

@开头的是一些常规标签，代表了不同的功能与内容。这里挑一些常用的标签作简短说明，很多都是字面上的意思，很容易理解。

@access 标签

用于指定成员（方法、属性）的访问权限，是最常用的标签之一，可选值为：

  • public：表示公共访问权限，即该成员可以被任何代码访问。
  • protected：表示受保护的访问权限，即该成员只能在当前类及其子类中访问。
  • private：表示私有访问权限，即该成员只能在当前类中访问。
  • internal：表示内部访问权限，即该成员只能在当前命名空间或包内部访问。

@var 标签

用于指定一个属性的数据类型和说明，它描述了类属性的类型以及属性的解释，是最常用的标签之一。

@var 语法：

@var ["Type"] [element_name] [<description>]

例如：上面的代码中@var string OR array;表示$image_crop的值是字符串或者数组。

@param 标签

用于描述函数或方法的参数，是最常用的标签之一。

语法：

@param [<Type>] [name] [<description>]

例如：@param  string  $color  Color string 方法的参数为字符串类型，名称为$color，描述为“Color string”（可以把它改成中文，例如：颜色值，字符串格式）

@return 标签

用于描述函数或方法的返回值，是最常用的标签之一。

语法：

@return [Type] [<description>]

例如：@return array RGB colors 该方法返回的值为数组格式，返回的值描述为“RGB颜色值”。

常见的标签还有：

@author 用于标记作者的信息，语法：@author [name] [<email address>]，示例可以见上面的代码@author A Little Duck <duck@lichil.com>。

@license 用于说明许可证适用信息，语法：@license [<url>] [name]。

@copyright 用于标记版权信息，语法：@copyright [description]。

@package 用于指定一个类、接口或者函数所属的包。这个标签通常出现在文档块注释的开头，用于向其他开发者说明这个类、接口或者函数属于哪个包，语法：@package [level 1][level 2][etc.]。

官网上还有许多标签未在此处陈列，基本上了解了上面几种就满足要求了，如果需要了解更多标签，请移步官网。

如果您在php文档中使用了标准的注释格式，可以将代码进行解析并生成文档

使用PHPDocumentor工具生成文档

如果您没有使用过phpDocumentor，可能需要先安装，然后在终端通过php-cli执行文档生成命令：

phpdoc run -d path/code -t path/output

其中，path/code 是您的代码所在的目录路径，path/output 是生成的文档输出目录路径。

php