? ? ? 為了提高工作效率，保證開發的有效性和合理性，并最大程度提高程序代碼的可讀性和可重復利用性，提高溝通效率，需要一份代碼編寫規范。讓大家養成良好的代碼編寫習慣，同時減少代碼中的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 = off
output_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中的變量用一個美元符號后面跟變量名表示。變量名區分大小寫。一個有效變景名由字母或者下畫線開頭，后面跟任意數量的字母、數字、下畫線。正常的正則表達式將表述為：[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。不建議下面這樣的函數名：getPublishedAdvertisementBy
CategoryAndCategoryldAndPosition()
上面的函數名可以提煉為：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;
