一塊兒學習ZF1-1.ZF 的 PHP 編碼標準

[摘自 Zend Framework 官方文檔] 

C.2. PHP File 文件格式 
C.2.1.  常規 
    對於只包含有 PHP 代碼的文件，結束標誌（"?>"）是不容許存在的，PHP自身不須要（"?>"）, 這樣作, 能夠防止它的末尾的被意外地注入相應。 
    重要： 由 __HALT_COMPILER() 容許的任意的二進制代碼的內容被 Zend Framework 中的 PHP 文件或由它們產生的文件禁止。這個功能的使用只對一些安裝腳本開放。

C.2.2.  縮進
    縮進由四個空格組成，禁止使用製表符 TAB 。

C.2.3.  行的最大長度 
    一行 80 字符之內是比較合適，就是說，ZF 的開發者應當努力在可能的狀況下保持每行代碼少於 80 個字符，在有些狀況下，長點也能夠, 但最多爲 120 個字符。 

C.2.4.  行結束標誌 
    行結束標誌遵循 Unix 文本文件的約定，行必需以單個換行符（LF）結束。換行符在文件中表示爲 10，或16進制的 0x0A。 
    注：不要使用 蘋果操做系統的回車（0x0D）或 Windows 電腦的回車換行組合如（0x0D,0x0A）。 

C.3.  命名約定 
C.3.1.  類 
    Zend Framework 的類命名老是對應於其所屬文件的目錄結構的，ZF 標準庫的根目錄是 「Zend/」，ZF 特別（extras）庫的根目錄是 "ZendX/"，全部 Zend Framework 的類在其下按等級存放。 
    類名只容許有字母數字字符，在大部分狀況下不鼓勵使用數字。下劃線只容許作路徑分隔符；例如 Zend/Db/Table.php 文件裏對應的類名稱是 Zend_Db_Table。 
    若是類名包含多個單詞，每一個單詞的第一個字母必須大寫，連續的大寫是不容許的，例如 「Zend_PDF」 是不容許的，而 "Zend_Pdf" 是可接受的。 
    這些約定爲 Zend Framework 定義了一個僞命名空間機制。若是對開發者在他們的程序中切實可行，Zend Framework 將採用 PHP 命名空間特性（若是有的話）。 
    參見在標準和特別庫中類名做爲類名約定的例子。 重要： 依靠 ZF 庫展開的代碼，但又不是標準或特別庫的一部分（例如程序代碼或不是 Zend 發行的庫），不要以 "Zend_" 或 "ZendX_" 開頭。 

C.3.2.  文件名 
    對於其它文件，只有字母數字字符、下劃線和短橫線（"-"）可用，空格是絕對不容許的。 
    包含任何 PHP 代碼的任何文件應當以 ".php" 擴展名結尾，衆所周知的視圖腳本除外。下面這些例子給出 Zend Framework 類可接受的文件名： 
    Zend/Db.php
    Zend/Controller/Front.php
    Zend/View/Helper/FormRadio.php
文件名必須遵循上述的對應類名的規則。 

C.3.3.  函數和方法 
    函數名只包含字母數字字符，下劃線是不容許的。數字是容許的但大多數狀況下不鼓勵。 
    函數名老是以小寫開頭，當函數名包含多個單詞，每一個子的首字母必須大寫，這就是所謂的 「駝峯」 格式。 
    咱們通常鼓勵使用冗長的名字，函數名應當長到足以說明函數的意圖和行爲。 
    這些是可接受的函數名的例子： 
    filterInput()
    getElementById()
    widgetFactory()

    對於面向對象編程，實例或靜態變量的訪問器老是以 "get" 或 "set" 爲前綴。在設計模式實現方面，如單態模式（singleton）或工廠模式（factory）， 方法的名字應當包含模式的名字，這樣名字更能描述整個行爲。 
    在對象中的方法，聲明爲 "private" 或 "protected" 的， 名稱的首字符必須是一個單個的下劃線，這是惟一的下劃線在方法名字中的用法。聲明爲 "public" 的從不包含下劃線。 
    全局函數 (如："floating functions") 容許但大多數狀況下不鼓勵，建議把這類函數封裝到靜態類裏。 

C.3.4.  變量 
    變量只包含數字字母字符，大多數狀況下不鼓勵使用數字，下劃線不接受。 
    聲明爲 "private" 或 "protected" 的實例變量名必須以一個單個下劃線開頭，這是惟一的下劃線在程序中的用法，聲明爲 "public" 的不該當如下劃線開頭。 
    對函數名（見上面 3.3 節）同樣，變量名總以小寫字母開頭並遵循「駝峯式」命名約定。 
    咱們通常鼓勵使用冗長的名字，這樣容易理解代碼，開發者知道把數據存到哪裏。除非在小循環裏，不鼓勵使用簡潔的名字如 "$i" 和 "$n" 。若是一個循環超過 20 行代碼，索引的變量名必須有個具備描述意義的名字。 

C.3.5.  常量 
    常量包含數字字母字符和下劃線，數字容許做爲常量名。 
    常量名的全部字母必須大寫。 
    常量中的單詞必須如下劃線分隔，例如能夠這樣 EMBED_SUPPRESS_EMBED_EXCEPTION 但不準這樣 EMBED_SUPPRESSEMBEDEXCEPTION。 
    常量必須經過 "const" 定義爲類的成員，強烈不鼓勵使用 "define" 定義的全局常量。 

C.4.  編碼風格 
C.4.1. PHP 代碼劃分（Demarcation）
    PHP 代碼老是用完整的標準的 PHP 標籤訂界： 
<?php

?>
短標籤（ ）是不容許的，只包含 PHP 代碼的文件，不要結束標籤 （參見 Section C.2.1, 「 常規 」）。 

C.4.2.  字符串 
C.4.2.1.  字符串文字 
    當字符串是文字(不包含變量)，應當用單引號（ apostrophe ）來括起來： 
    $a = 'Example String';

C.4.2.2.  包含單引號（'）的字符串文字 
    當文字字符串包含單引號（apostrophe ）就用雙引號括起來，特別在 SQL 語句中有用： 
    $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
    在轉義單引號時，上述語法是首選的，由於很容易閱讀。 

C.4.2.3.  變量替換 
    變量替換有下面這些形式： 
    $greeting = "Hello $name, welcome back!";
    $greeting = "Hello {$name}, welcome back!";
    爲保持一致，這個形式不容許： 
    $greeting = "Hello ${name}, welcome back!";

C.4.2.4.  字符串鏈接 
    字符串必需用 "." 操做符鏈接，在它的先後加上空格以提升可讀性：
    $company = 'Zend' . ' ' . 'Technologies';
    當用 "." 操做符鏈接字符串，鼓勵把代碼能夠分紅多個行，也是爲提升可讀性。在這些例子中，每一個連續的行應當由 whitespace 來填補，例如 "." 和 "=" 對齊： 
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

C.4.3.  數組 
C.4.3.1.  數字索引數組 
    索引不能爲負數，建議數組索引從 0 開始。 
    當用 array 函數聲明有索引的數組，在每一個逗號的後面間隔空格以提升可讀性： 
    $sampleArray = array(1, 2, 3, 'Zend', 'Studio');

    能夠用 "array" 聲明多行有索引的數組，在每一個連續行的開頭要用空格填補對齊： 
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);

C.4.3.2.  關聯數組 
    當用聲明關聯數組，array 咱們鼓勵把代碼分紅多行，在每一個連續行的開頭用空格填補來對齊鍵和值： 
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
C.4.4.  類 
C.4.4.1.  類的聲明 
    用 Zend Framework 的命名約定來命名類。 
    花括號應當從類名下一行開始(the "one true brace" form)。 
    每一個類必須有一個符合 PHPDocumentor 標準的文檔塊。 
    類中全部代碼必需用四個空格的縮進。 
    每一個 PHP 文件中只有一個類。 
    放另外的代碼到類裏容許但不鼓勵。在這樣的文件中，用兩行空格來分隔類和其它代碼。 

下面是個可接受的類的例子： // 459 9506 － 441 9658 下次從這裏開始 
/**
 * Documentation Block Here
 */
class SampleClass
{
    // 類的全部內容
    // 必需縮進四個空格
}

C.4.4.2.  類成員變量 
    必須用Zend Framework的變量名約定來命名類成員變量。 
    變量的聲明必須在類的頂部，在方法的上方聲明。 
    不容許使用 var （由於 ZF 是基於 PHP 5 的 ），要用 private、 protected 或 public。 直接訪問 public 變量是容許的但不鼓勵，最好使用訪問器 （set/get）。 

C.4.5.  函數和方法 
C.4.5.1.  函數和方法聲明 
    必須用Zend Framework的函數名約定來命名函數。 
    在類中的函數必須用 private、 protected 或 public 聲明它們的可見性。 
    象類同樣，花括號從函數名的下一行開始(the "one true brace" form)。 
    函數名和括參數的圓括號中間沒有空格。 
    強烈反對使用全局函數。 
下面是可接受的在類中的函數聲明的例子： 
/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // 函數的全部內容
        // 必需縮進四個空格
    }
}
注： 傳址（Pass-by-reference）是在方法聲明中容許的惟一的參數傳遞機制。  

/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar(&$baz)
    {}
}

傳址在調用時是嚴格禁止的。 
返回值不能在圓括號中，這妨礙可讀性並且若是未來方法被修改爲傳址方式，代碼會有問題。 

/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * WRONG
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RIGHT
     */
    public function bar()
    {
        return $this->bar;
    }
}

C.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);

C.4.6.  控制語句 
C.4.6.1. if/Else/Elseif
    使用 if and elseif 的控制語句在條件語句的圓括號先後都必須有一個空格。 
    在圓括號裏的條件語句，操做符必須用空格分開，鼓勵使用多重圓括號以提升在複雜的條件中劃分邏輯組合。 
    前花括號必須和條件語句在同一行，後花括號單獨在最後一行，其中的內容用四個空格縮進。 
if ($a != 2) {
    $a = 2;
}

    對包括"elseif" 或 "else"的 "if" 語句，和 "if" 結構的格式相似， 下面的例子示例 "if" 語句， 包括 "elseif" 或 "else" 的格式約定： 
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

    在有些狀況下， PHP 容許這些語句不用花括號，但在(ZF) 代碼標準裏，它們（"if"、 "elseif" 或 "else" 語句）必須使用花括號。 
    "elseif" 是容許的但強烈不鼓勵，咱們支持 "else if" 組合。 

C.4.6.2. Switch
    在 "switch" 結構裏的控制語句在條件語句的圓括號先後必須都有一個單個的空格。 
    "switch" 裏的代碼必須有四個空格縮進，在"case"裏的代碼再縮進四個空格。 
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}

switch 語句應當有 default。 
    注： 有時候，在 falls through 到下個 case 的 case 語句中不寫 break or return 頗有用。 爲了區別於 bug，任何 case 語句中，全部不寫 break or return 的地方應當有一個 "// break intentionally omitted" 這樣的註釋來代表 break 是故意忽略的。   C.4.7.  註釋文檔  C.4.7.1.  格式      全部文檔塊 ("docblocks") 必須和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文檔的範圍，關於它的詳情，參考：http://phpdoc.org/。      全部類文件必須在文件的頂部包含文件級 （"file-level"）的 docblock ，在每一個類的頂部放置一個 "class-level" 的 docblock。下面是一些例子：  C.4.7.2.  文件      每一個包含 PHP 代碼的文件必須至少在文件頂部的 docblock 包含這些 phpDocumentor 標籤：  /**  * 文件的簡短描述  *  * 文件的詳細描述（若是有的話）... ...  *  * LICENSE: 一些 license 信息  *  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)  * @license    http://framework.zend.com/license/3_0.txt   BSD License  * @version    $Id:$  * @link       http://framework.zend.com/package/PackageName  * @since      File available since Release 1.5.0 */ C.4.7.3.  類      每一個類必須至少包含這些 phpDocumentor 標籤：  /**  * 類的簡述  *  * 類的詳細描述 （若是有的話）... ...  *  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)  * @license    http://framework.zend.com/license/   BSD License  * @version    Release: @package_version@  * @link       http://framework.zend.com/package/PackageName  * @since      Class available since Release 1.5.0  * @deprecated Class deprecated in Release 2.0.0  */ C.4.7.4.  函數      每一個函數，包括對象方法，必須有最少包含下列內容的文檔塊（docblock）：      函數的描述      全部參數      全部可能的返回值      由於訪問級已經經過 "public"、 "private" 或 "protected" 聲明， 不須要使用 "@access"。      若是函數/方法拋出一個異常，使用 @throws 於全部已知的異常類：      @throws exceptionclass [description]