Zend Framework的PHP编码规范【2】

4.4. 类

4.4.1. 类的声明

类的声明应该遵守以下要求：

l        大括号必须写在类名字的下一行；

l        每个类都必须有一个遵守PHPDocumentor标准的注释文档块；

l        类内部的代码都必须缩进4个空格；

l        一个PHP文件只允许有一个类；

l        在一个类文件里可以放置其他代码，但不提倡，对于这种情况，必须使用2个空行，把类代码和其他PHP代码分开。

下面是一个规范的类的声明：

/**

* 文档注释块

*/

class SampleClass

{

    // 类的内部代码

    // 必须缩进4个空格

}

4.4.2. 类成员变量

成员变量的命名必须遵守变量命名规则。

类成员变量的声明必须位于类的顶部，在函数 定义之前。

不允许使用var关键字，成员变量的声明必须使用关键字：private、protected或者public。尽管可以通过把变量声明为public，以便直接访问成员变量，但本规范推荐使用get/set存取符来访问变量。

4.5. 函数与方法

4.5.1. 函数与方法的定义

函数命名必须遵循命名规范。

类内部的函数必须使用private、protected和public等关键字，表示该函数的可见性。

函数里大括号的用法与类一致，即大括号必须位于函数名字的下一行，函数名字与括号之间没有空格。

强烈建议不要使用全局范围函数。

下面是规范的类成员函数的书写方法：

/*

* 文档注释块

*/

function sampleMethod($a)

{

    // 函数的内部内容

    // 必须缩进4个空格

}

注意： 只有在函数定义阶段允许传递“引用传递变量”：

function sampleMethod(&$a)

{}

调用阶段不允许使用引用传递变量。

返回值（return）不允许使用括号。

function foo()

{

    // 错误的写法

    return($this->bar);

    // 正确的写法

    return $this->bar;

}

4.5.2. 函数和方法的用法

如果函数有多个参数，需要在每个逗号后面添加一个空格，参看下面的例子：

threeArguments(1, 2, 3);

调用阶段不允许传递引用传递参数，而应该把他放在函数定义阶段。

对于允许使用数组参数的函数，函数调用允许使用array声明语句，并且允许分割成多行，同时需要通过缩进保持可读性，例如下面的例子：

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',

                     $a, $b, $c,

                     56.44, $d, 500), 2, 3);

4.6. 控制语句

4.6.1. if / else / elseif

控制语句中if和elseif关键字之后，必须一个空格与后面的左括号分割，右括号后面也必须有一个空格。

在括号里面的条件语句，操作符两边必须有空格以保持可读性，如果括号里的条件较多，建议根据逻辑分组通过添加括号。

左大括号应该写在条件语句的同一行，而右大括号应该独自放在一行，括号内部的内容应该缩进4个字符。

if ($a != 2) {

    $a = 2;

}

对于包含有elseif或else的if语句，其格式要求参照如下例子：

if ($a != 2) {

    $a = 2;

} else {

   $a = 7;

}

if ($a != 2) {

    $a = 2;

} elseif ($a == 3) {

   $a = 4;

} else {

   $a = 7;

}

尽管PHP允许在某些情况下这些语句里可以不使用大括号，但我们的编码规范里不允许这么做，所有的if、elseif和else语句都必须使用大括号。

尽管允许使用elseif结构，但我们更推荐使用"else if"组合。

4.6.2. Switch

对于控制语句switch，用于包含条件语句部分的左右括号，其左括号前和右括号后都必须有一个空格。

switch内部的内容，都必须缩进4个空格，每个case语句下的内容也同样缩进4个空格。

switch ($numPeople) {

    case 1:

        break;

    case 2:

        break;

    default:

        break;

}

switch语句中都必须有一个default语句，不能省略。

注意： 在某些时候，为了让一个 case语句在完成操作之后直接跳到下一个 case语句，而有意去掉 break或 return语句。为了把这种情况与 bug区别，建议在需要省略掉 break或 return的地方添加注释： "// 这里有意去掉 break语句（ break intentionally omitted） "。

4.7. 内部文档化

4.7.1. 文档格式

所有的文档块（即docblocks）都必须遵循phpDocumentor格式，这里不对phpDocumentor格式多做介绍，具体请参考网站http://phpdoc.org

所有为Zend Framework写的或者使用Zend Framework的源代码文件，都必须在每个文件顶部包含文件级的文档块，以及在每个类定义的上边包含类级的文档块，下面就是文档块的例子。

4.7.2. 文件级文档块

任何包含PHP代码的文件都必须在其顶部包含文档块，并至少包含以下phpDocumentor标记：

/**

* 关于本文件的简要说明

*

* 关于本文件的详细描述（如果有的话）...

*

* LICENSE: 许可信息

*

* @copyright  2005 Zend Technologies

* @license    http://www.zend.com/license/3_0.txt   PHP License 3.0

* @version    CVS: $Id:$

* @link       http://dev.zend.com/package/PackageName

* @since      File available since Release 1.2.0

*/

4.7.3. 类级别文档块

每个类级别的文档块都必须至少包含以下phpDocumentor标记：

/**

* 类的简单说明

*

* 类的详细说明 (如果有的话)...

*

* @copyright  2005 Zend Technologies

* @license    http://www.zend.com/license/3_0.txt   PHP License 3.0

* @version    Release: @package_version@

* @link       http://dev.zend.com/package/PackageName

* @since      Class available since Release 1.2.0

* @deprecated Class deprecated in Release 2.0.0

*/

4.7.4. 函数级文档块

每个函数，包括对象方法，都必须包含至少下列文档块：

l        函数功能描述

l        所有的参数

l        所有可能返回的值

这里不必使用@access标记，因为用来声明函数的public、private或者protected等关键字已经指明了访问级别。

如果函数或方法可能抛出异常，需要使用“@throws:”标记，例如：

@throws exceptionclass [描述]