PHP編碼規范-筆記

所有的代碼都要變成可供他人容易閱讀的 

良好的代碼書寫習慣 + 良好的注釋習慣 + PhpDocumentor = 程式說明書 

整理日期:2013-07-30

為什么要編碼規范：

編碼規范(code conventions)對于程式員而言尤為重要，有以下幾個原因：

1.在一個軟體的生命周期中，80%的花費用于維護，

2.幾乎沒有任何一個軟體在其整個生命周期中均由最初的開發人員來維護，

3.編碼規范可以改善軟體的可讀性，可以讓程式員盡快而徹底地理解新的代碼，

規范不是真理，它無關對錯與是非，它影響的是您的習慣，您不遵循規范，您的代碼依舊可以正常運行，但您不是一個人在戰斗，因此，我們還是希望您能嚴格遵循此規范，另外，沒有一成不變的規則，也有很多規則沒有定義到的地方，如果您對本規范有何意見或建議，請您反饋過來，我們會“謹慎修改，嚴格執行”，

第1章 排版規則

1.1 縮進規范

所有的縮進使用空格取代Tab制表符，縮進的單位為 4 個空格，

說明: 以免用不同的編輯器閱讀程式時，因 Tab 鍵所設定的空格數目不同而造成程式布局變化，雖然使用空格會增加檔案的大小,但在局域網中幾乎可以忽略,且在編譯程序中也可被消除掉，

1.2 大括號規范

(1) 程式塊的分界符大括號'{'和'}'，應各獨占一行并且位于同一列，同時與參考它們的陳述句左對齊，

(2) 在函式體的定義，類的定義，以及if、for、do、while、switch、case陳述句中的左大括號'{'應放在行尾，與右括號')'之間用一個空格隔開， 右大括號'}'應與左大括號'{'所在行的行首處在同一列，比如：

function outer($a, $b) {

    for ( $i = 0; $i < 10; $i++ ) {
        $a += $b;
    }

    return $a;
}

(3) if、for、do、while等陳述句的執行陳述句部分無論多少都要加括號{}，比如：

if ( true == $a ) {
    return;
}

1.3 空格規范

(1) 括號內側(左括號后面，右括號前面)不應有空格，比如：

intval($a);

$b[0];

(2) 語法關鍵字(if, for , while, switch 等)后必須加空格，比如：

if ($count > 100) {
    // program code
}

(3) 函式名與左括號之間不應該有空格，這能幫助區分關鍵字和函式呼叫，比如：

$a = intval($a);
if ($a) {
    //code
}

(4) 所有的二元運算子(+, -, *, /, =, >, <, ==, &&, ||等等)應用空格將其與運算元隔開，比如：

$a + $b;    //算術運算子

$a = $b;    //賦值運算子

$a > $b;    //比較運算子

$a && $b;    //邏輯運算子

(5) 一元運算子(++, --, !)與其運算元之間不應有空格,除非運算子是個單詞,比如typeof，比如：

$a++;

--$a;

!$a;

(6) 每個逗號','后應跟一個空格，比如：

get_db_info($host, $user, $passwd);

(7) 每個控制部分(比如for陳述句)中的分號';'后須跟一個空格，比如：

for ( $i = 0; $i < 10; $i++ ) {
    //code
} 

(8) 字串連接符'.'前后都加空格，比如：

$my_name = 'file_' . $var1;

(9) 匿名函式在function和左括號'('之間應有一個空格，

$a = function ($e) {
    return $e;
};

(10) 右花括號'}'后緊接有內容，括號后要加空格，比如：

if ( $a > $b ) {
    //code
} else {
    //code
}

1.5 換行規范

(1) if、for、do、while、case、switch、default等陳述句自占一行，比如:

if ( NULL == $user ) {
    //code
}

(2) 較長的陳述句（>80字符）要分成多行書寫，長運算式要在低優先級運算子處劃分新行，運算子放在新行之首，劃分出的新行要進行適當的縮進，使排版整齊，陳述句可讀，比如:

if ((taskno < max_act_task_number)
    && (stat_stat_item_valid(stat_item))) {
    // program code
}

for (i = 0, j = 0;
    (i < first_word_length) && (j < second_word_length);
    i++, j++) {
    // program code 
}

1.6 空行規范

誰也不愿意看到擠在一堆的無序的代碼，我們在寫代碼的時候總是會利用一些空行來增加代碼可讀性，合理的利用空格來區分代碼段會使代碼的邏輯思路更加明確，我們強行規定的空行有以下情況：

(1) <?php 之后必須有且只有1個空行

(2) 兩個函式之間必須有1個空行，

(3) return、die、exit之前如果有其他陳述句的情況下應加上一個空行，

(4) 相對獨立的程式塊之間、變數說明之后必須加空行，

第2章  命名規范

2.1 命名方式

規范使用三種書寫方式：

(1) Pascal 命名規則

將識別符號的每個單詞的首字母都大寫，

例如：BackColor

(2) Camel 命名規則

識別符號的首字母小寫，而后面連接的單詞的首字母都大寫，

例如：backColor

(3) Linux C命名規則

變數所有字母都使用小寫，使用'_'作為每個詞的分界，

變數名必須有一定的意義，并且意義準確，禁止拼音命名法，

例如：有一個變數用于保存圖書的數目，可以命名為number_of_book或者num_of_book，不建議使用i,j,n等，因為它沒有意義，也不建議使用 number或book，因為意義不準確，

2.2 區域變數

所有變數都要預先宣告，并注明其意義,在函式的首部定義所有的變數，不要使用一個宣告一個，盡量減少全域變數的使用，不要讓區域變數覆寫全域變數，

變數所有字母都使用小寫，使用'_'作為每個詞的分界，變數名字應該使用名詞或者形容詞+名詞的方式，如$value，$new_value，

例如:

function handleError($errorNumber) {
    $error = osErr($errorNumber);
    $time_of_error = osErr->GetTimeOfError();
    $error_processor = osErr->GetErrorProcessor();
}

2.3 全域變數命名

全域變數使用 g_ 前綴，

例如:

global $g_Log;

2.4 靜態變數命名

靜態變數使用 s_ 前綴，如:  $s_value，

2.5 臨時變數命名

不要將在回圈中頻繁使用的臨時變數如$i,$j等用于其它用途，

2.6 方法/函式中引數命名

引數的名字使用 Camel 命名方法，

2.7 全域常量

全域常量全部大寫，用'_'分隔每個單詞，

理由:

這是命名全域常量的傳統，您要注意不要與其它的定義相沖突，

例如:

define('A_GLOBAL_CONSTANT', 'Hello world!');

2.8 類命名

用 Pascal 命名規則（首字母大寫），盡量謹慎的使用縮寫，不要用下劃線作類名單詞連接符，

在類中，屬性定義在前邊，公用方法放到專用方法前邊，

對于派生類的命名應該避免帶其父類名的傭訓，一個類的名字只與它自身有關，和它的父類叫什么無關，

一個類對應到一個檔案，存放類的檔案采用 ClassName.class.php 方式命名，

2.9 類屬性命名

類中的屬性使用Camel 命名法，

2.10 類方法命名

類中的方法使用Camel命名法，命名建議使用動賓結構(動詞+名詞,如addUser)或系表結構(如isLocked)的方式，

2.11 函式命名

函式名字采用 C GNU 的慣例，所有的字母使用小寫字母，使用'_'分割單詞，

理由：

這樣容易與類方法區分開，

例如：

function some_body_function() { }

2.12 私有屬性與私有方法命名

以 _ 開頭，如

private $_privateValue;
private static $_sPrivateStaticValue;
private function _initialize() {
    // program code
};

2.13 縮寫詞不要全部使用大寫字母

無論如何，當遇到以下情況，您可以用首字母大寫其余字母小寫來代替全部使用大寫字母的方法來表示縮寫詞，

使用: getHtmlStatistic.

不使用: getHTMLStatistic.

部分約定俗成的縮寫除外，比如PDO 類別庫本身全大寫，那么 class MyPDO extends PDO{}是合理的，

第3章 編程規范

3.1 陣列的定義

(1) 關聯陣列定義和使用時中 key 值前后必須加單引號，并且每個元素占一行，比如：

array(
    'name' => 'd5s.cn',
    'gender' => 'php'
);

(2) 索引陣列定義所有元素位于同一行，比如，

array('a', 'b', 'c');

3.2 引號的使用

(1) 引號統一使用'單引號，只有當引號重疊時才使用"雙引號，這樣每行程可以節省幾百 K 記憶體，

(2) 使用"號自動轉義變數時必須在變數前后加"{}"，比如，

$str = "Marry is {$age}";

3.3 if 陳述句

雖然在 PHP 中else if 和 elseif 的作用基本上是一樣的，但是為了代碼的統一性（也有傳言 else if 會出現不穩定的情況），我們要求將 elseif 之間不保留空格，if陳述句應如以下格式:

if (condition) {
     //statements;
} elseif (condition) {
     //statements;
} else {
     //statements;
}

3.4 避免嵌入式的賦值

比如，避免這樣書寫

$d = ($a = $b + $c) + $r;

3.5 避免沒有含義的數字

一個在源代碼中使用了的赤裸裸的數字，包括作者，在三個月后，沒人會知道它的含義，

使用 define()來給您想表示某樣東西的數值一個真正的名字，而不是采用赤裸裸的數字，例如:

define("PRESIDENT_WENT_CRAZY", "22");
define("WE_GOOFED", "19");
define("THEY_DIDNT_PAY", "16");
 

if (PRESIDENT_WENT_CRAZY == $foo) {
    start_thermo_nuclear_war();
} elseif (WE_GOOFED == $foo) {
    refund_lotso_money();
} elseif (THEY_DIDNT_PAY == $foo) {
    infinite_loop();
} else {
    happy_days_i_know_why_im_here();
}

3.6 總是將恒量放在等號的左邊

主要原因是假如您在等式中漏了一個等號，語法檢查器會為您報錯，比如：

if (6 == $errorNum) {
    //code
}

3.7 return 陳述句

一條有回傳值的return陳述句不要使用括號'()'來括住回傳值，

3.8 回圈計數器

允許使用一個單字符變數名的唯一情形是當它作為一個回圈計數器的時候，在這種情況下，外層回圈的計數器應當始終是 $i，如果有一個回圈處于這個回圈的內部，它的計數器應當是 $j，進而是 $k，等等，如果回圈的計數器是一個已經存在并且名字有意義的變數，本規范并不適用，例如：

for ($i = 0; $i < $outer_size; $i++) {
    for ($j = 0; $j < $inner_size; $j++) {
       foo($i, $j);
    }
}

3.9 SQL規則

(1) 在 PHP 中嵌入的 SQL 陳述句關鍵字全部采用大寫；

(2) 表名和欄位名要用反引號(`)引起來以防止因為欄位名中包含空格而出現錯誤；

(3) 資料值兩邊用單引號包括(')，并且應確保資料值中的單引號已經轉義以防止 SQL 注入；

(4) 能使用多表查詢一次查詢的資料要一次讀完，避免多次查詢資料庫，

比如：

$sql = "SELECT `user`.`name` FROM `user` WHERE `id` = '{$id}' LIMIT 1";

 3.10 三元運算子

三元運算子，在一行代碼里只允許使用一級，三元運算子只應該用來做簡單的事情，它們只適合拿來做賦值用，根本不是用來做函式呼叫或者任何復雜的事情的，

示例：不應該使用它們的地方

(($i < $size) && ($j > $size)) ? do_stuff($foo) : do_stuff($bar);

示例：使用它們的合適地方

$min = ($i < $j) ? $i : $j;

3.11 初始化變數

變數使用前應初始化，使用未初始化變數將報E_NOTICE錯誤，這些錯誤可以通過使用內嵌的 isset() 或者empty()函式檢查一個變數是否被設定來避免，

示例： 老辦法

if ($forum) …

新辦法：

if (!empty($forum)) …

if (isset($forum)) …

3.12 輸入變數的初始化

無論是函式的引數還是通過URL傳遞的變數，在呼叫之前均必須對其進行預處理以及設定默認值，

字串必須進行trim及轉義的處理,并且如果變數的值是在我們預計的范圍之內，需要對變數的非法值做出相應的處理；對于數字型的變數則需要進行intval或者floatval的處理，

3.13 其他雜項

(1) 純PHP檔案去掉底部的"?>"，

(2) 所有PHP、HTML檔案均保存為No Bom UTF-8的字符編碼，

(3) 不允許把多個短陳述句寫在一行中，即一行只寫一條陳述句，

(4) 一個函式僅完成一件功能,不要設計多用途面面俱到的函式，

第4章 注釋規則

4.1 函式頭部注釋

每個函式之前應當有注釋，告訴一個程式員使用這個函式所需要知道的事情，注釋應該確保其他人不必察看這個函式的代碼，就可以自信地在自己的代碼中呼叫這個函式，注釋包括的資訊：

        /** 
         * 函式的含義說明
         * @param mixed $arg1 引數一的說明
         * @param mixed $arg2 引數二的說明
         * @access public
         * @return bool 回傳值說明
         * @author 作者
         */

4.2 洗掉廢除的注釋

廢除的注釋,注釋的代碼要及時洗掉，

4.3 常量加注釋

對于所有有物理含義的變數、常量，如果其命名不是充分自注釋的，在宣告時都必須加以注釋，說明其物理含義，變數、常量的注釋應放在其上方相鄰位置或右方，示例：

// active statistic task number
define('MAX_ACT_TASK_NUMBER', 1000);

define('MAX_ACT_TASK_NUMBER', 1000);    // active statistic task number

4.4 資料結構宣告加注釋

資料結構宣告(陣列)，必須加以注釋，對資料結構的注釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的注釋放在此域的右方，

示例：

// sccp interface with sccp user primitive message name

$sccp_user_primitive = array(
    'N_UNITDATA_IND' => 1, // sccp notify sccp user unit data come
    'N_NOTICE_IND'   => 2, // sccp notify user the No.7
    'N_UNITDATA_REQ' => 3  // sccp user's unit data
);

4.5 全域變數注釋

全域變數要有較詳細的注釋，包括對其功能、取值范圍、哪些函式或程序存取它以及存取時注意事項等的說明，

4.6 注釋縮排

注釋與所描述內容進行同樣的縮排，可使程式排版整齊，并方便注釋的閱讀與理解，如：

function example_fun() {
    //fdgfd
    CodeBlock One 

    // code two comments
    CodeBlock Two
}

4.7 將注釋與其上面的代碼用空行隔開，如：

// code one comments
program code one 

// code two comments
program code two

4.8 連續case注釋

對于switch陳述句下的case陳述句，如果因為特殊情況需要處理完一個case后進入下一個case處理，必須在該case陳述句處理完、下一個case陳述句前加上明確的注釋，這樣比較清楚程式撰寫者的意圖，有效防止無故遺漏break陳述句，示例：

switch ($i) {
    case 'CMD_INIT':
        echo 'i equals 0';
        break;
    case 'CMD_START':
        echo 'i equals 1';    // now jump into case CMD_A
    case 'CMB_A':
        echo 'i equals 2';
        break;
}

4.9 注釋格式

注釋格式統一，單行注釋必須使用//，多行使用一對/*…*/

4.10 注釋以中文為主

注釋應考慮程式易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能用非常流利準確的英文表達，

4.11 記錄所有的空陳述句

總是記錄下for或者是while的空塊陳述句，以便清楚的知道該段代碼是漏掉了，還是故意不寫的，

for ( $i = 0; $i < 100; $i++ ) {
    // 慷訓圈
}

標籤：PHP

上一篇：給你看看小白博主開發的打賞系統

下一篇：php判斷是否為數字