原文 : http://kbs.kimbs.cn/blog/list/post/25/title/zend-framework-coding-standards-for-php-coding-style
Zend Framework 中的 Php 编码标准 (三) - 编码风格
1. PHP 代码必须以完整的形式来定界,短定界符只能用在视图。
例如 :
// Php code here
?>
// index.phtml
'hello' ?>
复制代码
2. 当一个字符串是纯文字组成的时候(即不含有变量),则必须总是以单引号(')或者撇号(`)作为定界符。
例如 :
$a
=
'Example String'
;
$b
= `
Excute Something
`;
复制代码
3. 当一个字符串含有撇号(`)的时候,我们允许使用双引号(")来定界字符串,特别是在些 SQL 语句的时候。
例如 :
$sql
=
"SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'"
;
复制代码
4. 变量替换中的变量只允许用 $+变量名 的形式。
例如 :
$greeting
=
"Hello $name, welcome back!"
;
// 允许
$greeting
=
"Hello {$name}, welcome back!"
;
// 允许
$greeting
=
"Hello ${name}, welcome back!"
;
// 不允许
复制代码
5. 多个字符串必须用点号 "." 来连接,且字符串与点号间必须用一个空格隔开。
例如 :
$company
=
'Zend'
.
'Technologies'
;
复制代码
6. 当用点号 "." 连接各字符串的时候,我们允许把它分割成多行以增强可读性。在这种情况下,点号 "." 必须与等于号 "=" 对齐。
例如 :
$sql
=
"SELECT `id`, `name` FROM `people` "
.
"WHERE `name` = 'Susan' "
.
"ORDER BY `name` ASC "
;
复制代码
7. 任何负数都不允许作为数组的索引,数组索引必须以任何非负数作为开头,而且强烈建议以0作为默认开头。
例如 :
$sampleArray
= array(-
1
=> -
1
,
0
=>
0
);
// 错误
$sampleArray
= array(
0
=> -
1
,
1
=>
0
);
// 正确
$sampleArray
= array(
1
=> -
1
,
2
=>
0
);
// 正确
复制代码
8. 当用 array 类型符号来构造数组的时候,必须在每个逗号之后加上一个空格来增强可读性。
例如 :
$sampleArray
= array(
1
,
2
,
3
,
'Zend'
,
'Studio'
);
复制代码
9. 多行的索引数组同样允许用 array 类型符号来构造,只是我们需要为每行的每个值加上必要的空格来保持其整齐美观。
例如 :
$sampleArray
= array(
1
,
2
,
3
,
'Zend'
,
'Studio'
,
$a
,
$b
,
$c
,
56.44
,
$d
,
500
);
复制代码
10. 当使用 array 类型符声明关联数组的时候,我们鼓励把它分成多个行,只是我们必须同时保证每行的键与值的对齐,以保持美观。
例如 :
$sampleArray
= array(
'firstKey'
=>
'firstValue'
,
'secondKey'
=>
'secondValue'
);
复制代码
11. 中括号的开始必须在类名的下一行顶格。
例如 :
class
foo
{
// 正确 {} 写法
}
class
foo
{
// 错误 {} 写法
}
复制代码
12. 类定义必须拥有符合 phpDocumentor 标准的注释块。
例如 :
/**
* 类定义注释
*/
class
Zend_Class
{
}
复制代码
13. 类中的所有代码都必须用4个空格来进行缩进。
例如 :
class
Zend_Class
{
$spaces
=
'4 spaces'
;
if (
$spaces
==
'4 spaces'
) {
echo
'is permitted !'
;
}
}
class
Zend_Class
{
$spaces
=
'less then 4 spaces'
;
if (
$spaces
!=
'4 spaces'
) {
echo
'is not permitted !'
;
}
}
复制代码
14. 每个 php 文件只允许声明一个类。在类文件里面写其它代码是允许的,但并不鼓励这样做。假如真要附加代码的话,必须用空行来分隔。
例如 :
// 允许但并不鼓励这样做
class Zend_Class
{
static $foo = 'foo' ;
}
echo Zend_Class :: $foo ;
php
/**
* 在同一文件里声明超过两个类是不允许的
*/
class Class_One
{
}
class Class_Two
{
}
?>
复制代码
15. 任何类变量的声明都必须放在类顶部,先于任何函数的声明。
例如 :
// 正确
class
right
{
public
$foo
=
'先于函数定义'
;
public function
fun
()
{
}
}
// 错误
class
wrong
{
public function
fun
()
{
}
public
$foo
=
'后于函数定义'
;
}
复制代码
16. 不允许用 var 符号来声明变量,类成员变量必须以 private,protected 和 public 来声明。其次,把类成员声明为 public 而直接引用虽然是允许的,但通常更好的方法是使用 get 和 set 方法来访问类成员。
例如 :
class
foo
{
var
$unpermitted
=
'这是不允许的!'
;
private
$privateVariable
=
'私有变量'
;
protected
$protectedVariable
=
'保护变量'
;
public
$publicVariable
=
'公共变量'
;
public function
setPrivateVariable
(
$value
)
{
$this
->
privateVariable
=
$value
;
}
public function
getPrivateVariable
()
(
return
$this
->
privateVariable
;
)
}
$foo
= new
foo
();
// 不鼓励使用
echo
$foo
->
publicVariable
;
// 鼓励使用
echo
$foo
->
getPrivateVariable
();
复制代码
17. 方法和函数必须总是用 private,protected 或者 public 来声明其作用域。
例如 :
class
foo
{
function
goo
()
{
// 不允许的
}
private function
bar
()
{
// 正确
}
protected function
baz
()
{
// 正确
}
public function
zoo
()
{
// 正确
}
}
复制代码
18. 按照 php 社区的习惯,静态 static 方法应该声明其作用域。
例如 :
class
foo
{
static function
baz
()
{
// 不允许的
}
public static function
bar
()
{
// 正确
}
}
复制代码
19. 对于类成员函数和方法,中括号的开始必须位于函数和方法名的下一行顶格。
例如 :
class
foo
{
public function
braceIsUnderneath
()
{
// 正确
}
public function
braceIsNotUnderneath
() {
// 错误
}
}
复制代码
20. 在函数名与参数括号之间不允许出现多余的空格。
例如 :
class
foo
{
public function
someSpacesAfterMe
(
$a
)
{
// 错误
}
public function
noSpacesAfterMe
(
$a
)
{
// 正确
}
}
复制代码
21. 引用只允许定义在函数参数中,实时传递引用是禁止的。
例如 :
function
defineRefInMethod
(&
$a
)
{
$a
=
'a'
;
}
function
callTimePassRef
(
$a
)
{
$a
=
'a'
;
}
$b
=
'b'
;
$c
=
'c'
;
// 允许的
defineRefInMethod
(
$b
);
echo
$b
;
// 'a'
// 禁止的
callTimePassRef
(&
$c
);
echo
$c
;
// 'a'
复制代码
22. 函数返回值不可以用括号包住,不然会降低可读性,而且假如以后函数修改为返回引用的话,这将会抛出一个异常。
例如 :
class
foo
{
public
$bar
=
'bar'
;
public function
goo
()
{
return (
$this
->
bar
);
}
public function &
zoo
()
{
return (
$this
->
bar
);
}
}
$foo
= new
foo
();
// 看起来没问题
echo
$foo
->
goo
();
/**
* 程序会抛出一个 notice 说 :
* "Only variable references should be returned by reference"
*/
echo
$foo
->
zoo
();
复制代码
23. 鼓励尽量使用类型提示,特别是在模块设计中。
例如 :
class
Zend_Component
{
public function
foo
(
SomeInterface $object
)
{}
public function
bar
(array
$options
)
{}
}
复制代码
24. 尽量避免同时使用异常处理和类型提示,来检验参数的有效性。
例如 :
class
Not_Zend_Class
{
}
class
foo
{
public function
bar
(
Zend_Class $zc
)
{
}
public function
goo
(
$zc
)
{
if (!
$zc
instanceof
Zend_Class
) {
throw new
Exception
(
'$zc 不是 Zend_Class 的实例'
);
}
}
}
$foo
= new
foo
();
$zc
= new
Not_Zend_Class
();
/**
* Catchable fatal error 错误显示 :
* "Argument 1 passed to foo::bar() must be an instance of Zend_Class,
* instance of Not_Zend_Class given"
*/
$foo
->
bar
(
$zc
);
/**
* 错误信息 : '$zc 不是 Zend_Class 的实例'
*/
try {
$foo
->
goo
(
$zc
);
} catch (
Exception $e
) {
echo
$e
->
getMessage
();
}
复制代码
25. 函数参数必须用 逗号+空格 来分隔。
例如 :
// 正确
threeArguments
(
1
,
2
,
3
);
// 错误
threeArguments
(
1
,
2
,
3
);
复制代码
26. 对于参数为数组的函数,参数中的数组应该分成多行以增强可读性。
例如 :
threeArguments
(array(
1
,
2
,
3
),
2
,
3
);
threeArguments
(array(
1
,
2
,
3
,
'Zend'
,
'Studio'
,
$a
,
$b
,
$c
,
56.44
,
$d
,
500
),
2
,
3
);
复制代码
27. 基于 “if”, "else" 和 "else if" 的条件控制里,我们必须用空格间隔开语句和括号。
例如 :
// 正确
if (
$spaceOutSide
) {
// ...
} else if (
$spaceOutSide
) {
// ...
} else {
// ...
}
// 错误
if(
$noSpaceOutSide
){
// ...
}else if(
$noSpaceOutSide
){
// ...
}else{
// ...
}
复制代码
28. 在条件控制语句的条件括号内,必须用空格将操作符与其它元素隔开。如果遇到很长的逻辑判断,则鼓励用内嵌括号来分割各个逻辑。
例如 :
if ((
$a
!=
2
) and (
$b
==
1
)) {
$a
=
$b
;
}
复制代码
29. 中括号的开始 "{" 必须与条件控制语句位于同一行,结束 "}" 必须总是独占一行且顶格,控制流程内容必须用4个空格进行缩进。
例如 :
// 正确
if (
$braceSameLine
) {
echo
'很好 : 4空格缩进'
;
}
// 错误
if (
$braceNotSameLine
)
{
echo
'不好 : 2空格缩进'
;
}
复制代码
30. 在某些场合,php 允许条件控制语句舍弃中括号 "{}" ,但是根据此编码规范,所有 "if", "else if" 或 "else" 语句都必须使用中括号 "{}" 定界内容。
例如 :
// 用 "{}" 定界内容是正确的
if (
$a
!=
2
) {
$a
=
2
;
} else if (
$a
==
3
) {
$a
=
4
;
} else {
$a
=
7
;
}
// 没有用 "{}" 定界是错误的
if (
$a
!=
2
)
$a
=
2
;
else if (
$a
==
3
)
$a
=
4
;
else
$a
=
7
;
复制代码
31. "elseif" 语句是不允许的,必须使用 "else if" 。
例如 :
if (
true
) {
//
} else if {
// 正确
}
if (
true
) {
//
} elseif {
// 错误
}
复制代码
32. "switch" 条件控制语句中,必须用空格将待测参数与其它元素分隔开。
例如 :
switch (
$num
) {
// 正确
}
switch(
$num
){
// 错误
}
复制代码
33. "switch" 语句的内容必须以4个空格缩进,"case" 条件控制的内容必须再加4个空格进行缩进。
例如 :
switch (
$indentedSpaces
) {
case
2
:
echo
"错误"
;
break;
case
4
:
echo
"正确"
;
break;
default:
break;
}
复制代码
34.在 "switch" 语句中应该总是包括 "default" 控制。
例如 :
switch (
$isWithDefault
) {
case
false
:
break;
default:
echo
"有 'default' 控制是正确的"
;
break;
}
switch (
$isWithDefault
) {
case
false
:
echo
"没有 'default' 控制是错误的"
;
break;
}
复制代码
35. 有时候我们需要在 "case" 语境中省略掉 "break" 或 "return" ,这个时候我们必须为这些 "case" 语句加上 "// break intentionally omitted" 注释。
例如 :
switch (
$numPeople
) {
case
1
:
// break intentionally omitted
case
2
:
break;
default:
break;
}
复制代码
36. 关键词 "global" 是不允许使用的,请用 $GLOBAL[xxx] 替代。
例如 :
$a
=
'a'
;
function
foo
()
{
// 错误
global
$a
;
$foo
=
$a
;
// 正确
$foo
=
$GLOBALS
[
'a'
];
return
$foo
;
}
echo
foo
();
复制代码
.