PHP注释规范
通用注释写法
一、文件的注释通用样例（普通程序文件，类文件，函数文件，变量定义文件）
1
2
3
4
5
6
7
8
9
10
11
12
| /**
* XXXXX的文件
*
* 功能1： xxx
* 功能2： xxx
*
* @file $Source: /home/doc/php开发注释规范.md $
* @package core
* @author Joy <[email protected]>
* @version $Id: php开发注释规范.txt,v 1.1 2014/03/04 20:37:46 Joy Exp $
* @link http://www.joychao.cc
*/
|
@file 行在提交了svn之后，会自动被补充为如下样式：
1
| * @file $Source: /home/doc/php开发注释规范.md $
|
@version 行在提交了svn之后，会自动被补充为如下样式：
1
| * @version $Id: php开发注释规范.txt,v 1.1 2014/03/04 20:37:46 Joy Exp $
|
@package 是团队事先定义好的，在phpdocumentor里同一package的文件可以给出跟踪的链接。项目开发前需要对其定义。
@link 行后面接的地址是程序开发文档的地址，因为我们目前没有在线的程序开发文档库，所以可不加。
注意注释的排版，左端保持对齐。
说明：以上自动更新版本及文件名需要配置svn，具体请自行google ‘SVN自动版本号’
二、类的注释，使用如下几个tag
1
2
3
4
5
6
7
8
9
10
11
12
13
| /**
* xxxxx类
*
* 功能1：完成xxxx
* 功能2：完成xxxxx
*
* @author Joy <[email protected]>
* @access public
* @abstract
*/
public class DemoClass {
//code...
}
|
@access (public|private) 标记类是私有的还是公用的。@abstract标记该类是个抽象类
虽然我们使用的是php5，但目前程序类的编写仍然沿用的php4，因此@access和@abstract两项可加可不加。
三、类的属性定义
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| public class DemoClass {
/**
* 当前页码
*
* @var integer
*/
public $currentPageNumber;
/**
* 私有变量使用下划线开头
*
* @var string
*/
private $_instance;
}
|
四、普通函数和类中的函数注释
1
2
3
4
5
6
7
8
9
10
11
12
13
|
function getAvatarUrl($imageName, $size = 80)
{
return sprintf(SITE_URL . '/service/images/cropped_%s/'.$imageName, $size);
}
|
顺序按照author、param、return来放，区块间空行。
五、程序段落注释
段落注释和逻辑注释使用如下方式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
if($_GET['do'] == 'buy')
{
if($_POST['strCodeNum'])
{
}
}
if($_GET['do'] == 'list')
{
if($_POST['strCodeNum'])
{
}
}
|
PHPdoc规范
文档注释，无非“//”和“/**/”两种 ，自己写代码，就那么点，适当写几句就好了；但是一个人总有融入团队的一天，团队的交流不是那几句注释和一张嘴能解决的，还需要通用的注释标准。
PHPDoc是PHP文档注释的一个标准，可以帮助我们在注释文档时有规范，查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc，个人英文水平有限，可以参照原文。
文档翻译自：http://en.wikipedia.org/wiki/Phpdoc
标记|用途|描述
-|-
@abstract| |抽象类的变量和方法
@access|public, private or protected|文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author|张三 zhangsan@163.com|文档作者
@copyright|名称 时间|文档版权信息
@deprecated|version|文档中被废除的方法
@deprec| |同 @deprecated
@example|/path/to/example|文档的外部保存的示例文件的位置。
@exception| |文档中方法抛出的异常，也可参照 @throws.
@global|类型：$globalvarname|文档中的全局变量及有关的方法和函数
@ignore| |忽略文档中指定的关键字
@internal| |开发团队内部信息
@link|URL|类似于license 但还可以通过link找到文档中的更多个详细的信息
@name|变量别名|为某个变量指定别名
@magic| |phpdoc.de compatibility
@package|封装包的名称|一组相关类、函数封装的包名称
@param|如 $username 用户名|变量含义注释
@return|如 返回bool|函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see|如 Class Login()|文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since|version|记录什么时候对文档的哪些部分进行了更改
@static| |记录静态类、方法
@staticvar| |在类、函数中使用的静态变量
@subpackage| |子版本
@throws| |某一方法抛出的异常
@todo| |表示文件未完成或者要完善的地方
@var|type|文档中的变量及其类型
@version| |文档、类、函数的版本信息
PHPDoc注释实例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
| <?php
class Webpage extends Output implements PSI_Interface_Output
{
private $_language;
private $_template;
private $_templates = array();
private $_languages = array();
public function __construct()
{
parent::__construct();
$this->_getTemplateList();
$this->_getLanguageList();
}
private function _checkTemplateLanguage()
{
$this->_template = trim(PSI_DEFAULT_TEMPLATE);
if (!file_exists(APP_ROOT.'/templates/'.$this->_template.".css")) {
$this->_template = 'phpsysinfo';
}
$this->_language = trim(PSI_DEFAULT_LANG);
if (!file_exists(APP_ROOT.'/language/'.$this->_language.".xml")) {
$this->_language = 'en';
}
}
private function _getTemplateList()
{
$dirlist = CommonFunctions::gdc(APP_ROOT.'/templates/');
sort($dirlist);
foreach ($dirlist as $file) {
$tpl_ext = substr($file, strlen($file) - 4);
$tpl_name = substr($file, 0, strlen($file) - 4);
if ($tpl_ext === ".css") {
array_push($this->_templates, $tpl_name);
}
}
}
private function _getLanguageList()
{
$dirlist = CommonFunctions::gdc(APP_ROOT.'/language/');
sort($dirlist);
foreach ($dirlist as $file) {
$lang_ext = substr($file, strlen($file) - 4);
$lang_name = substr($file, 0, strlen($file) - 4);
if ($lang_ext == ".xml") {
array_push($this->_languages, $lang_name);
}
}
}
public function run()
{
$this->_checkTemplateLanguage();
$tpl = new Template("/templates/html/index_dynamic.html");
$tpl->set("template", $this->_template);
$tpl->set("templates", $this->_templates);
$tpl->set("language", $this->_language);
$tpl->set("languages", $this->_languages);
echo $tpl->fetch();
}
}
|
