php關於編碼規範的文檔（收藏）

為了提高工作效率，保證開發的有效性和合理性，並最大程度提高程式碼的可讀性和可重複利用性，提高溝通效率，需要一份代碼編寫規範。讓大家養成良好的代碼編寫習慣，同時減少代碼中的bug。
CleverCode整理了一些規範。本規範包含PHP開發時程式編碼中命名規範、代碼縮排規則、控制結構、函數調用、函數定義、注釋、包含代碼、PHP標記、常最命名等方面的規則。

1 檔案格式

1.1 檔案標記

所有PHP檔案，其代碼標記均使用完整PHP標籤，不建議使用短標籤，例如：

<?php  //推薦  echo 'hello world';  ?>      <?  //短標籤格式不推薦  echo ' hello world ';  ?>

1) 使用短標籤格式容易和XML混淆，並且不是所有PHP版本和伺服器都預設支援或開啟短標籤選項（從PHP5.4開始，php.ini中的短標籤選項不影響短標籤的使用）。對於只含有PHP代碼的檔案，將在檔案結尾處忽略?>。這是為了防止多餘空格或者其他字元影響到代碼。
2)實際上這個問題只有在不開啟壓縮或緩衝輸出時才會出現，例如：
php.ini-禁止壓縮輸出及緩衝輸出

zlib.output_conpression = offoutput_buffering = off

foo.php,注意這個時候有一些空格或分行符號掉在了之後，當然這在頁面上是看不
到的。

<?php      $foo= 'foo';  ?>

index.php,在包含foo.php的同時，實際上已經輸出一些空格或換行了。

<?php      include 'foo.php';      session_start();  ?>

這時將看到一個警告（warning)：“...Cannotsendsessioncachelimiter-headersalreadysent...”

1.2 檔案和目錄命名

程式檔案名稱和目錄名均採用有意義的英文命名，不使用拼音或無意義的字母，只允許出現字母、數字、下畫線和中畫線字元，同時必須以“.php”結尾（模板檔案除外）。
//類統一採用
DemoTest.php

2 命名規範

2.1 變數命名

PHP中的變數用一個貨幣符號後面跟變數名表示。變數名區分大小寫。一個有效變景名由字母或者下畫線開頭，後面跟任意數量的字母、數字、下畫線。正常的Regex將表述為：[a-zA-Z_\x7f-\xff][a-zA-ZO-9_'x7f-\xff],不應該在變數中使用中文等非ASCII字元。

2.1.1 程式整體

程式整體以駝峰法命名，以小寫字母開始，同時命名要有意義，如：

function displayName($name){      echo $name;  }

2.1.2 PHP全域變數索引值

PHP全域變數索引值兩邊都有中間使用駝峰法命名。

2.1.3 普通變數

普通變數整體採用駝峰法，
按照約定命名，並避免使用常用關鍵字或存在模糊意義的單詞。變數應該以名詞為主。
字串:$myName
數組:$myArray

不推薦：
$yes：不應該使用其作為bool型變童，因為變數很可能被改變，其可能使得Syeszflase,而讓其代碼邏輯變得混亂。
$sex：具有模糊意義且不地道的英文單詞，性別的命名應該是$gender。

2.1.4 函數名

函數名既要有意義，一看就知道要幹什麼，也要盡量縮寫。建議採用動詞或動詞加形容詞
的命名方式，如showMsg。不建議下面這樣的函數名：

getPublishedAdvertisementByCategoryAndCategoryldAndPosition()

上面的函數名可以提煉為：

getAd($category,$categoryid，$position,$published)

例如1）類公用函數：

public function doGetUserName($job)

例如2）類私人函數，以“_”開頭：

private function _doGetUserName($job)

例如3）類保護函數，以“_”開頭：

protected function _doGetUserName($job)

2.1.5 類中的屬性

類中的變數遵守普通變數的命名規則。
例如1）公用屬性，static屬性：

public $userName = ’CleverCode’;static $userType = array(1,2,3);

例如2）私人屬性，以“_”開頭：

private $_userName = ’CleverCode’;

例如3）保護屬性，以“_”開頭：

protected $_userName = ’CleverCode’;

例如4）常量，全部大寫，以“_”分隔：

const TYPE_GZ = 4;

2.2 資料庫命名

2.2.1 庫命名

1）使用小寫字母。（windows不區分大小寫，linux區分大小寫，為了庫移植相容，所以全部小寫）
2）多個單片語成，單詞之間用"_"分隔。
例如：

db_user,db_system。

2.2.2 表命名

1)表名均使用小寫字母。
2)表名字使用統一的首碼，且首碼不可為空（模組化，且可有效規避MYSQL保留字）。
3)對於多個單片語成的表名，使用"_"間隔。
例如：

pre_users,pre_user_shop

2.2.3 表欄位命名

1)全部使用小寫字母命名。
2)多個單詞不用下畫線進行分割（重要）。
3)如果有必要，給常用欄位加上表名首字母作為首碼。
4)避免使用關鍵字和保留字，但約定俗成的除外。
例如：

username,newsid,userid，logid

3 注釋規範

3.1 檔案注釋

檔案注釋通常放在整個PHP檔案頭部，其內容包括檔案著作權、作者、編寫日期、版本號碼等
重要訊息。PHP中，可以參照phpdocument規範，便於利用程式自動產生文檔。
檔案注釋遵循以下規則：
1)必須包含本程式的描述；
2)必須包含作者；
3)必須包含著作權；
4)必須包含檔案的名稱；
5)可以包含書寫日期；
6)可以包含版本資訊；
7)可以包含重要的使用說明，如類的調用方法、注意事項等。
例如：

<?php      /**   * SystemUser.php   *    * 系統使用者操作操作   *   * Copyright (c) 2015 http://blog.csdn.net/CleverCode   *   * modification history:   * --------------------   * 2015/5/11, by Clever Code, Create   *

3.2 類與介面注釋

類和介面的注釋應該盡量簡潔。按照一般的習慣，一個檔案只包含一個類，在類注釋中通常不需要再加上作者和版本等資訊，加上可見度和簡中的描述即可。如果檔案注釋已經足夠詳細,可以不用給類寫注釋。如果同時存在介面和介面的實作類別，通常做法是僅在介面中進行注釋。

3.3 方法和函數注釋

方法和函數的注釋寫在前面，通常需要標明的資訊主要是可見度、參數類型和傳回值的類
例如1：

/**   * 對比新舊資料   *   * @param bigint $userid 人編號   * @param array $oldMap 舊資料   * @param array $newMap 新資料（輸出參數）   * @return string 成功返回'OK'，失敗返回錯誤資訊   */   public static function diffRecommendInfo($userid, $oldMap, &$newMap){   }

例如2：

/**   * 插入日誌資料   *   * @param bigint $data[‘userid’] 使用者編號   * @param array $data[‘logintime’] 登入時間   * @return string 成功返回'OK'，失敗返回錯誤資訊   */   public static function insertLogData($data){   }

3.4 Action注釋

由於我們都是使用的zend開發模式，在Action是http請求處理邏輯的入口，那麼必然會傳遞get,post等參數。可以注釋如下.
例如1）沒有get,post傳遞參數時候：

/**      * 自動化佈建名稱      *      * @return void      */      public function autosetAction(){  }

例如2 ）有get傳遞參數時候：

/**      * 擷取使用者名稱稱      *      * @get int $userid 使用者編號      * @get int $currpage 當前頁      * @get int $pagesize      *      * @return void      */  public function getusernameAction(){  }

例如3） 有post傳遞參數時候：

/**      * 刪除使用者      *      * @post int $userid 使用者編號      * @return void      */  public function deleteuserAction(){  }

3.5 單行注釋

1)寫在被注釋代碼前面，而不是後面。但對於單行語句，按照習慣可以把注釋放在語句末尾,也可以寫在行上面。
2)對於大段注釋，使用/**/格式，通常在檔案和函數注釋中使用，而代碼內部統一使用//注釋，因為其寫起來簡單。
例如：
//姓名

$name = ’CleverCode’;

4 代碼風格

4.1 縮排與空格

在書寫代碼的時候，必須注意代碼的縮排規則：
1)使用4個空格作為縮排，而不使用tab縮排（如在UltraEdit中可以進行預先設定）。
2)變數賦值時，等號左右留出空格。
例如：
$name = 'CleverCode';//推薦
$name='CleverCode';//不推薦

為了最大程度減輕工作量，保持代碼美觀，建議使用大型IDE管理代碼。比如，在zend studio中，使用Ctrl+Shift+F按鍵組合對代碼進行格式化。

4.2 語句斷行

代碼書寫中應遵循以下原則：
1)盡量保證程式語句一行就是一句；
2)盡量不要使一行的代碼太長，一般控制在80個字元以內；
如果一行代碼太長，請使用類似.=的方式斷行書寫；
執行資料庫的SQL語句操作時，盡量不要在函數內寫SQL語句，而先用變數定義SQL
語句，然後在執行操作的函數中調用定義的變數。
例如：

//代碼分割$sql= "SELECTusername,password,address,age,postcode from test_t";$sql.= "WHEREusername=${user}";$ret = mysql_query($sql);

3)一個函數控制在200行以內；
4)if最多嵌套3層；
//不推薦

If(){      If(){          If(){              If(){                  ……              }          }      }  }

5)迴圈最多3層。

//不推薦  For(){      For(){          For(){              For(){                  ……              }          }      }  }

6)if或者for語句塊中只有一行時候，加上{}。當有語句變動的時候會帶來不必要的bug。

//推薦  If($a == 1){      echo 1;  }    //不推薦  If($a == 1) echo 1;

4.3 空行

1）函數與函數之間空行。
2）同一個函數不同邏輯塊之間空行，查閱不同的邏輯塊條理更清晰。

4.4 函數結構

通常一個函數分為三部分。第一部分：檢查參數；第二部分：處理邏輯；第三部分：返回結果。
例如：

/**  * 刪除日誌通過uid  *  * @param string $uid 使用者uid  * @return string 成功返回'OK'，失敗返回錯誤資訊  */  public static function deleteLogByUid($uid){          //第一步：檢查參數。防止處理部分異常；比如$uid是傳入array();      if (!is_numeric($uid)) {          return '!is_numeric($uid)';      }            //第二步：處理邏輯。      $affected = $userLogTable->delete('where userid = ' . $uid);            //第三步：返回結果。讓調用者知道是否處理正常。      if($affected){          return 'OK';      }            return 'delete error!';  }

4.5 函數返回函數

需要用戶端的函數：
傳回值

$ret = array(‘code’=> 1 ,msg=>’’,data => array());

4.6 更好的習慣

在代碼中，使用下面列舉的寫法，可以使代碼更優雅。
1)多使用PHP中已經存在的常量，而不要自己定義，例如：

echo$meg."\r\n";echo$msg,PHPJEOL;

PHP中，PHP_EOL是一個預定義常量，表示一行結束，隨著所使用系統的不同，使用PHP_EOL會讓代碼更具有可移植性。

2)更詳盡的注釋。
注釋是一門藝術，好的注釋可以比代碼更精彩。不用擔心效率問題。一則注釋對代碼的效
率影響不大，其次在正式產品中可以對代碼中的注釋進行大量刪除。注釋做到極致和完美的典型代表是Apache組織各種產品的原始碼。

3)不要濫用文法糖。
文法糖也就是語言中的潛規則，即不具有普遍代表性的文法。少量使用文法糖會嘗到甜
頭，大量使用則是一種災難。
例如以下代碼，可讀性比較差；

$a?$a-$b:3&&$c&&$d=1;