• home > OMD > codeGuide >

    phpc代码规范:PHPDocument代码注释规范总结

    Author:zhoulujun Date:

    好的注释能让你的代码读起来更轻松,而且在重构,维护方面,后人不会诅咒前任。Code Guide,需要一个模板,然后让编辑器IDEA来规范团队代码质量。

    php、JavaScript,相比写java,总是凌乱的1B。配合,规范下团伙产出质量

    代码是用来写完后,还是需要维护的,需要维护,代码可读性,没有注释,读个球。

    php注释列表

    • @abstract 申明变量/类/方法

    • @access 指明这个变量、类、函数/方法的存取权限

    • @api 表示这是一个提供给第三方使用的API接口

    • @author 函数作者的名字和邮箱地址

    • @category 组织packages

    • @copyright 指明版权信息

    • @const 指明常量

    • @deprecated 指明不推荐或者是废弃的信息

    • @example 示例

    • @exclude 指明当前的注释将不进行分析,不出现在文挡中

    • @final 指明这是一个最终的类、方法、属性,禁止派生、修改。

    • @global 指明在此函数中引用的全局变量

    • @include 指明包含的文件的信息

    • @internal 仅限内部使用的,如仅限内部测试使用

    • @ignore  忽略 可以通过此标记让phpDocumentor忽略其中一个,以免生成重复的文档。

    • @link 定义在线连接 例如@link http://g.cn 不懂滚去问谷歌,别来烦我

    • @license 协议 例如@license GPL

    • @module 定义归属的模块信息

    • @method 方法。这是用在类注释里的标记。特别适合一些动态加载的类,IDE无法自动提示出来,这时就可以通过写@method标记来告诉IDE我这类里有哪些方法

    • @modulegroup 定义归属的模块组

    • @name 名字

    • @package 定义归属的包的信息 php没有包,所以就用来表示命名空间 例如@package yii\base\db

    • @param 定义函数或者方法的参数信息

    • @property 类属性,与@method类似,可以告诉IDE我这类里有哪些属性 例如@property int id 用户id

    • @property-read 只读的属性。例如__get魔术方法能够取到的属性 例如@property-read int id 用户id

    • @property-write 只可写的属性。例如__set魔术方法能够设置的属性  例如@property-write string name 用户名

    • @return 定义函数或者方法的返回信息 例如@return array

    • @see 定义需要参考的函数、变量,并加入相应的超级连接。 参考,类似@link,可与@deprecated联动 例如@see \yii\base\db::tableName() 旧方法table_name已弃用,请使用此方法替代

    • @since 指明该api函数或者方法是从哪个版本开始引入的,例如从1.0之后添加了xx功能、删除了xx参数等。例如@since 1.0.2 添加了$b参数

    • @static 指明变量、类、函数是静态的。

    • @throws 指明此函数可能抛出的错误异常,极其发生的情况 例如@throws LifeException 没钱了,好想死啊

    • @todo 指明应该改进或没有实现的地方

    • @uses 例如@uses \yii\base\db::$count 使用此属性计数

    • @var 定义说明变量/属性。 例如@var int id 用户id

    • @version 定义版本信息 例如@version 1.0.1 2016-07-03更新 或者@version GIT:1f3197d01 来自GIT分支1f3197d01

    php注释模板

    <?php
    /**
     * 文件名简单介绍
     *
     * 文件功能 这是一个什么文件
     * @author zhoulujun.cn 作者
     * @version 1.0 版本号
     * @date 2020-02-02
     */
    
    
    /**
     * 类的介绍
     *
     * 类的详细介绍(可选。)。
     * @author richard<[email protected]>
     * @since 1.0
     */
    class Test{
    
    }
    /**
     * 函数的含义说明
     *
     * @access public
     * @author 作者
     * @param string $arg1 参数一的说明,字符串类型
     * @param string|boolean $arg2 参数二的说明,字符串或者布尔
     * @param mixed $arg2 参数二的说明  这是一个混合类型
     * @return array 返回类型,数组
     * @date 2020-02-02
     */
    function getDemo($arg1,$arg2,$arg3){
    
    }



    转载本站文章《phpc代码规范:PHPDocument代码注释规范总结》,
    请注明出处:https://www.zhoulujun.cn/html/Operation/codeGuide/8160.html

    延伸阅读: