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 [描述]