针对PHP开发规范，有必要总结一下，与各位分享

用过IDE或看过其他源码的小伙伴们应该都见过类似下面这样的注释

/*** 递归获取所有游戏分类* @param int $id* @return array*/

看得多了就大概知道了一些规律。为了使自己的代码更加规zhuang范bi，也开始有样学样地写着这些注释。其实这种注释格式是有自己的名字的，它就叫——PHPDOC。

1、介绍

PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor
这样的外部文档生成器生成 API 文档，也可以帮助一些例如 Zend Studio, NetBeans, ActiveState
Komodo Edit and IDE 和 Aptana Studio 之类的集成开发环境
理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。

PHPDoc 可 同时支持面向对象 的和 面向过程 的代码。

简单来说PHPDOC可以用来自动生成API文档。主流的IDE都会识别它，并在你coding中给予你相应的智能提示。使用PHPDOC有以下好处：

让你的代码更加规zhuang范bi，更易于理解
让你的IDE更懂你的代码，更加智能的提示和自动完成
如需API手册，可使用 phpDocumentor 来自动生成

2、常规使用

有关phpDoc的完整文档位于phpDocumentor官网。以下仅为整理的常用规范。

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

@author
作者
格式@author [名称] [<邮箱>]
例如@author Leroi <leroiliu@163.com>

@copyright
版权声明。例如很多网站底部都有
格式@copyright [描述]
例如@copyright 1949-2019 China

@deprecated
不建议使用的、已过期的、将被删除的
格式@deprecated [<版本号>] [<描述>]
例如@deprecated 1.0.0 新版本将不再包含此函数
如果它是被其他方法所取代了，建议添加@see标记

@example
例子、示例、用例。也可表示方法返回值的例子
格式@example [位置] [<起始行号> [<行数>] ] [<描述>]
例如@example demo.php 10 3 使用示例

@global
全局变量
格式@global [类型][名称][描述]
类型@global string name 用户名

@ignore
忽略
格式@ignore [<描述>]
例如你在if和else的语句块中定义分别同一个变量但值不同时，可以通过此标记让phpDocumentor忽略其中一个，以免生成重复的文档。例如

if ($ostest) {/*** This define will either be 'Unix' or 'Windows'*/define("OS","Unix");} else {/*** @ignore*/define("OS","Windows");}

@internal
仅限内部使用的
格式@internal [描述]
例如@internal 仅限内部测试使用

@license
协议，很常见的啦
格式@license [<url>] [名称]
例如@license GPL

@link
链接，可用于辅助说明、引用文档等
格式@link [url] [<描述>]
例如@link https://www.google.com/ 谷歌

@method
方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE无法自动提示出来，这时就可以通过写@method标记来告诉IDE我这类里有哪些方法
格式@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
静态方法格式@method static [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提问，返回答案内容

@package
包。但php没有包，所以就用来表示命名空间
例如@package yii\base\db

@param
参数，用于函数和方法注释里的标记
格式@param [Type] [name] [<description>]
例如@param string title 文章标题

@property
类属性，与@method类似，可以告诉IDE我这类里有哪些属性
格式@property [Type] [name] [<description>]
例如@property int id 用户id

@property-read
只读的属性。例如__get魔术方法能够取到的属性
格式@property-read [Type] [name] [<description>]
例如@property-read int id 用户id

@property-write
只可写的属性。例如__set魔术方法能够设置的属性
格式@property-write [Type] [name] [<description>]
例如@property-write string name 用户名

@return
返回值
格式@return [类型] [<描述>]]
例如@return array 结果数组

@see
参考，类似@link，可与@deprecated联动
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tableName() 旧方法table_name已弃用，请使用此方法替代

@since
从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等
格式@since [1.0.0] [<描述>]
例如@since 1.0.2 添加了$b参数

@throws
可能会抛出的错误类型
格式@throws [类型] [<描述>]
例如@throws LifeException 没钱了，好想死啊

@todo
待办。提示自己或他人还需要做些什么
格式@todo [描述]
例如@todo 这个类还没做异常处理

@uses
使用
格式@uses [完整方法名] [<描述>]
例如@uses \yii\base\db::$count 使用此属性计数

@var
变量
格式@var [类型] [变量名] [<描述>]
例如@var int id 用户id

@version
版本号
格式@version [<载体>] [<描述>]
例如@version 1.0.1 2016-07-03更新
或者@version GIT:1f3197d01 来自GIT分支1f3197d01

PHP注释规范（PHPDOC）总结相关推荐

doxygen 注释规范_编程规范 - doxygen注释规范示例（C++）
doxygen注释规范示例(C++) doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写. ...
使用VA助手如何快速添加注释(按doxygen注释规范)
原文首发于微信公众号「3D视觉工坊」:使用VA助手如何快速添加注释(按doxygen注释规范) 首先,关于VA助手的破解安装教程,请参考:VS2015 Visual Assist X 破解版安装教程 ...
PHP中类和文件的代码注释规范
编写好的文档对于任何软件项目都至关重要,不仅是因为文档的质量可能比代码的质量更重要,还因为良好的第一印象会促使开发人员进一步查看代码以及后续的迭代. 文件注释 /*** Sample file com ...
c++ doxygen 注释规范_C语言代码注释参考
简述该参考是基于Doxygen注释规范进行简单归纳,可以适当根据自己的需求进行约定. Doxygen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX.RTF参考手册.简单 ...
详细聊聊Javadoc注释规范
Javadoc 注释规范 1. 注释分类 2. Java文档和Javadoc 3. 文档注释的格式 3.1 文档和文档注释的格式化 3.2 文档注释的三部分 4. 使用Javadoc标记 4.1 ...
java的注释规范_Java 注释规范
基本的要求: 1.注释形式统一在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范 ...
java 注释超链接_java_Java代码注释规范详解，代码附有注释对程序开发者来 - phpStudy...
Java代码注释规范详解代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一在整个应 ...
c++ doxygen 注释规范_[代码规范]Go语言编码规范指导
本规范旨在为日常Go项目开发提供一个代码的规范指导,方便团队形成一个统一的代码风格,提高代码的可读性,规范性和统一性.本规范将从命名规范,注释规范,代码风格和 Go 语言提供的常用的工具这几个方面做一 ...
doxygen注释规范示例（C++）
doxygen注释规范示例(C++) doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写. ...
Java 语法规定之外的命名注释规范
Java 语法规定之外的命名注释规范命名规范 1. 项目名 2. 包名 3. 类名 4. 常量名 5. 变量名 6. 方法名 8. 其它命名技巧 9. 应当避免的行为 10. 经典的命名法 11. ...

PHP注释规范（PHPDOC）总结

1、介绍

2、常规使用

PHP注释规范（PHPDOC）总结相关推荐

最新文章

热门文章