關於PHP開發編碼規範

作者：中國資訊網 來源：zixuen.com
加入時間：2005-5-12　

2.
命名規則

2.1. 合適的命名

命名是程式規劃的核心。古人相信只要知道一個人真正的名字就會獲得凌駕於那個人之上的不可思議的力量。只要你給事物想到正確的名字，就會給你以及後來的人帶來比程式碼更強的力量。別笑！

名字就是事物在它所處的生態環境中一個長久而深遠的結果。總的來說，只有瞭解系統的程式設計師才能為系統取出最合適的名字。如果所有的命名都與其自然相適合，則關係清晰，含義可以推導得出，一般人的推想也能在意料之中。

如果你發覺你的命名只有少量能和其對應事物相匹配的話， 最好還是重新好好再看看你的設計吧。

2.2. 類命名

·
在為類（class ）命名前首先要知道它是什麼。如果通過類名的提供的線索，你還是想不起這個類是什麼的話，那麼你的設計就還做的不夠好。
·
超過三個片語成的混合名是容易造成系統各個實體間的混淆，再看看你的設計，嘗試使用（CRC Session card)看看該命名所對應的實體是否有著那麼多的功用。

· 對於派生類的命名應該避免帶其父類名的誘惑，一個類的名字只與它自身有關，和它的父類叫什麼無關。
·
有時字尾名是有用的，例如：如果你的系統使用了代理（agent ），那麼就把某個部件命名為“下載代理”（DownloadAgent）用以真正的傳送資訊。

2.3. 方法和函式命名

·
通常每個方法和函式都是執行一個動作的，所以對它們的命名應該清楚的說明它們是做什麼的：用CheckForErrors()代替ErrorCheck()，用DumpDataToFile()代替DataFile()。這麼做也可以使功能和資料成為更可區分的物體。

· 有時字尾名是有用的:
o Max – 含義為某實體所能賦予的最大值。
o Cnt – 一個執行中的計數變數的當前值。
o
Key – 鍵值。
例如：RetryMax 表示最多重試次數，RetryCnt 表示當前重試次數。
· 有時字首名是有用的：
o Is
– 含義為問一個關於某樣事物的問題。無論何時，當人們看到Is就會知道這是一個問題。
o Get – 含義為取得一個數值。
o Set –
含義為設定一個數值
例如：IsHitRetryLimit。

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

·
無論如何，當遇到以下情況，你可以用首字母大寫其餘字母小寫來代替全部使用大寫字母的方法來表示縮寫詞。
使用: GetHtmlStatistic.

不使用: GetHTMLStatistic.
理由
·
當命名含有縮略詞時，人們似乎有著非常不同的直覺。統一規定是最好，這樣一來，命名的含義就完全可以預知了。

舉個NetworkABCKey的例子，注意C是應該是ABC裡面的C還是key裡面的C，這個是很令人費解的。有些人不在意這些，其他人卻很討厭這樣。所以你會在不同的程式碼裡看到不同的規則，使得你不知道怎麼去叫它。

例如
class FluidOz // 不要寫成 FluidOZ
class GetHtmlStatistic // 不要寫成
GetHTMLStatistic

2.5. 類命名

· 使用大寫字母作為詞的分隔，其他的字母均使用小寫
·
名字的首字母使用大寫
· 不要使用下劃線(`_`)
理由
· 根據很多的命名方式，大部分人認為這樣是最好的方式。
例如

class NameOneTwo
class Name

2.6. 類庫命名

·
目前名稱空間正在越來越廣泛的被採用，以避免不同廠商和團體類庫間的類名衝突。
·
當尚未採用名稱空間的時候，為了避免類名衝突，一般的做法是在類名前加上獨特的字首，兩個字元就可以了，當然多用一些會更好。
例如
John
Johnson的資料結構類庫可以用Jj做為字首，如下：
class JjLinkList
{
}

另一種折中方式是建立包含類庫目錄（事實上Java也是這麼做的），以不通的目錄代表不同的名稱空間。
例如

Microsoft的資料庫相關類庫可以在：
/classes/com/Microsoft/ Database/DbConn.php

Apache的資料庫相關類庫可在：
/classes/org/apache/Database/DbConn.php

2.7.
方法命名

· 採用與類命名一致的規則
理由
· 使用所有不同規則的大部分人發現這是最好的折衷辦法。
例如

class NameOneTwo
{
function DoIt() {};
function HandleError()
{};
}

2.8. 類屬**命名

· 屬**命名應該以字元‘m’為字首。
·
字首‘m’後採用於類命名一致的規則。
· ‘m’總是在名字的開頭起修飾作用，就像以‘r’開頭表示引用一樣。
理由
·
字首`m`防止類屬**和方法名發生任何衝突。你的方法名和屬**名經常會很類似，特別是存取元素。
例如
class NameOneTwo

{
function VarAbc() {};
function ErrorNumber() {};
var $mVarAbc;

var $mErrorNumber;
var $mrName;
}

2.9. 方法中引數命名

·
第一個字元使用小寫字母。
· 在首字元後的所有字都按照類命名規則首字元大寫。
理由
· 可以區分方法中的一般變數。
·
你可以使用與類名相似的名稱而不至於產生重名衝突。
例如
class NameOneTwo
{
function
StartYourEngines(
&$rSomeEngine,
&$rAnotherEngine);
}

2.10. 變數命名

· 所有字母都使用小寫
· 使用`_`作為每個詞的分界。
理由
·
通過這一途徑，程式碼中變數的作用域是清晰的。
· 所有的變數在程式碼中都看起來不同，容易辨認。
例如
function
HandleError($errorNumber)
{
$error = OsErr($errorNumber);

$time_of_error = OsErr->GetTimeOfError();
$error_processor =
OsErr->GetErrorProcessor();
}

2.11. 引用變數和函式返回引用

·
引用必須帶‘r’字首
理由
· 使得型別不同的變數容易辨認
· 它可以確定哪個方法返回可更改物件，哪個方法返回不可更改物件。

例如
class Test
{
var mrStatus;
function
DoSomething(&$rStatus) {};
function &rStatus() {};
}

2.12. 全域性變數

· 全域性變數應該帶字首‘g’。
理由
· 知道一個變數的作用域是非常重要的。
例如

global $gLog;
global &$grLog;

2.13. 定義命名 / 全域性常量

·
全域性常量用`_`分隔每個單詞。
理由
這是命名全域性常量的傳統。你要注意不要與其它的定義相沖突。
例如

define(“A_GLOBAL_CONSTANT”, “Hello world!”);

2.14. 靜態變數

·
靜態變數應該帶字首‘s’。
理由
· 知道一個變數的作用域是非常重要的。
例如
function test()
{

static $msStatus = 0;
}

2.15. 函式命名

· 函式名字採用C
GNU的慣例，所有的字母使用小寫字母，使用`_`分割單詞。
理由
· 這樣可以更易於區分相關聯的類名。
例如
function
some_bloody_function()
{
}

2.16. 錯誤返回檢測規則

·
檢查所有的系統呼叫的錯誤資訊，除非你要忽略錯誤。
· 為每條系統錯誤訊息定義好系統錯誤文字以便include。

3. 書寫規則

3.1. 大括號 {} 規則

在三種主要的大括號放置規則中，有兩種是可以接受的，如下的第一種是最好的：
·
將大括號放置在關鍵詞下方的同列處：
if ($condition) while ($condition)
{ {
… …

} }
· 傳統的UNIX的括號規則是，首括號與關鍵詞同行，尾括號與關鍵字同列：
if ($condition) { while
($condition) {
… …
} }
理由
·
引起劇烈爭論的非原則的問題可通過折衷的辦法解決，兩種方法任意一種都是可以接受的，然而對於大多數人來說更喜歡第一種。原因就是心理研究學習範疇的東西了。

對於更喜歡第一種還有著更多的原因。如果您使用的字元編輯器支援括號匹配功能的話（例如vi），最重要的就是有一個好的樣式。為什麼？我們說當你有一大塊的程式而且想知道這一大塊程式是在哪兒結束的話。你先移到開始的括號，按下按鈕編輯器就會找到與之對應的結束括號，例如：

if ($very_long_condition && $second_very_long_condition)
{

…
}
else if (…)
{
…
}

從一個程式塊移動到另一個程式塊只需要用游標和你的括號匹配鍵就可以了，不需找匹配的括號。

3.2. 縮排/製表符/空格 規則

· 使用製表符縮排。
· 使用三到四個空格為每層次縮排。
·
不再使用只要一有需要就縮排的方法。對於最大縮排層數，並沒有一個固定的規矩，假如縮排層數大於四或者五層的時候，你可以考慮著將程式碼因數分解(factoring
out code)。
理由
· 許多程式設計者支援製表符。
· 當人們使用差異太大的製表符標準的話，會使閱讀程式碼變得很費力。
·
如此多的人願意限定最大的縮排層數，它通常從未被看作是一件工作。我們相信程式設計師們會明智的選擇巢狀的深度。
例如
function func()

{
if (something bad)
{
if (another thing bad)
{
while
(more input)
{
}
}
}
}

3.3. 小括號、關鍵詞和函式 規則

·
不要把小括號和關鍵詞緊貼在一起，要用空格隔開它們。
· 不要把小括號和函式名緊貼在一起。
· 除非必要，不要在Return返回語句中使用小括號。

理由
· 關鍵字不是函式。如果小括號緊貼著函式名和關鍵字，二者很容易被看成是一體的。
例如
if (condition)

{
}

while (condition)
{
}

strcmp($s, $s1);

return 1;

3.4. 別在物件架構函式中做實際的工作

別在物件架構建構函式中做實際的工作，
建構函式應該包含變數的初始化和（或）不會發生失敗的操作。
理由
· 構造不能返回錯誤 。
例如
class Device

{
function Device() { /* initialize and other stuff */ }
function
Open() { return FAIL; }
};

$dev = new Device;
if (FAIL ==
$dev->Open()) exit(1);

3.5. If Then Else 格式

佈局

這由程式設計師決定。不同的花括號樣式會產生些微不同的樣觀。一個通用方式是：
if (條件1) // 註釋
{
}
else
if (條件2) // 註釋
{
}
else // 註釋
{
}
如果你有用到else if
語句的話，通常最好有一個else塊以用於處理未處理到的其他情況。可以的話放一個記錄資訊註釋在else處，即使在else沒有任何的動作。
條件格式

總是將恆量放在等號/不等號的左邊，例如：
if ( 6 == $errorNum ) …

一個原因是假如你在等式中漏了一個等號，語法檢查器會為你報錯。第二個原因是你能立刻找到數值而不是在你的表示式的末端找到它。需要一點時間來習慣這個格式，但是它確實很有用。

3.6. switch 格式

· 當一個case塊處理後，直接轉到下一個case塊處理，在這個case塊的最後應該加上註釋。

· default case總應該存在，它應該不被到達，然而如果到達了就會觸發一個錯誤。
· 如果你要創立一個變數，那就把所有的程式碼放在塊中。

例如
switch (…)
{
case 1:
…
// FALL THROUGH
case
2:
{
$v = get_week_number();
…
}
break;

default:

}

3.7. continue,break 和 ? 的使用

3.7.1. Continue 和 Break

Continue 和 break 其實是變相的隱蔽的 goto方法。
Continue 和 break 像 goto
一樣，它們在程式碼中是有魔力的，所以要節儉（儘可能少）的使用它們。使用了這一簡單的魔法，由於一些未公開的原因，讀者將會被定向到只有上帝才知道的地方去。

Continue有兩個主要的問題：
· 它可以繞過測試條件。
· 它可以繞過等/不等表示式。

看看下面的例子，考慮一下問題都在哪兒發生：
while (TRUE)
{
…
// A lot of code

…
if (/* some condition */) {
continue;
}
…
// A lot
of code
…
if ( $i++ > STOP_VALUE) break;
}
注意：”A lot of
code”是必須的，這是為了讓程式設計師們不能那麼容易的找出錯誤。
通過以上的例子，我們可以得出更進一步的規則：continue 和 break
混合使用是引起災難的正確方法。
3.7.2. ?:
麻煩在於人們往往試著在 ? 和 : 之間塞滿了許多的程式碼。以下的是一些清晰的連線規則：

· 把條件放在括號內以使它和其他的程式碼相分離。
· 如果可能的話，動作可以用簡單的函式。
·
把所做的動作，“?”，“:”放在不同的行，除非他們可以清楚的放在同一行。
例如
(condition) ? funct1() :
func2();

or

(condition)
? long statement
: another long
statement;

3.8. 宣告塊的定位

· 宣告程式碼塊需要對齊。
理由
· 清晰。
·
變數初始化的類似程式碼塊應該列表。
· &應靠近型別，而不是變數名。
例如
var $mDate
var&
$mrDate
var& $mrName
var $mName

$mDate = 0;
$mrDate =
NULL;
$mrName = 0;
$mName = NULL;

3.9. 每行一個語句

除非這些語句有很密切的聯絡，否則每行只寫一個語句。

3.10. 短方法

方法程式碼要限制在一頁內。

3.11. 記錄所有的空語句

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

while ($dest++ = $src++)
; // VOID

3.12. 不要採用預設方法測試非零值

不要採用預設值測試非零值，也就是使用：

if (FAIL != f())
比下面的方法好：

if
(f())

即使 FAIL 可以含有 0 值
，也就是PHP認為false的表示。在某人決定用-1代替0作為失敗返回值的時候，一個顯式的測試就可以幫助你了。就算是比較值不會變化也應該使用顯式的比較；例如：if
(!($bufsize % strlen($str)))應該寫成：if (($bufsize % strlen($str)) ==
0)以表示測試的數值（不是布林）型。一個經常出問題的地方就是使用strcmp來測試一個字元等式，結果永遠也不會等於預設值。

非零測試採用基於預設值的做法，那麼其他函式或表示式就會受到以下的限制:
· 只能返回0表示失敗，不能為/有其他的值。
·
命名以便讓一個真(true)的返回值是絕對顯然的，呼叫函式IsValid()而不是Checkvalid()。

3.13. 布林邏輯型別

大部分函式在FALSE的時候返回0，但是發揮非0值就代表TRUE，因而不要用1（TRUE，YES，諸如此類）等式檢測一個布林值，應該用0（FALSE，NO，諸如此類）的不等式來代替：

if (TRUE == func()) { …
應該寫成：

if (FALSE != func()) { …

3.14. 通常避免嵌入式的賦值

有時候在某些地方我們可以看到嵌入式賦值的語句，那些結構不是一個比較好的少冗餘，可讀**強的方法。

while ($a !=
($c = getchar()))
{
process the character
}

++和–操作符類似於賦值語句。因此，出於許多的目的，在使用函式的時候會產生副作用。使用嵌入式賦值提高執行時**能是可能的。無論怎樣，程式設計師在使用嵌入式賦值語句時需要考慮在增長的速度和減少的可維護**兩者間加以權衡。例如：

a = b + c;
d = a + r;
不要寫成：

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

雖然後者可以節省一個週期。但在長遠來看，隨著程式的維護費用漸漸增長，程式的編寫者對程式碼漸漸遺忘，就會減少在成熟期的最優化所得。

4. 幫助與共享

4.1. 重用您和其他人的艱苦工作

跨工程的重用在沒有一個通用結構的情況下幾乎是不可能的。物件符合他們現有的服務需求，不同的過程有著不同的服務需求環境，這使物件重用變得很困難。

開發一個通用結構需要預先花費許多的努力來設計。當努力不成功的時候，無論出於什麼原因，有幾種辦法推薦使用：

4.2.
請教！給群組發Email求助

這個簡單的方法很少被使用。因為有些程式設計師們覺得如果他向其他人求助，會顯得自己水平低，這多傻啊!做新的有趣的工作，不要一遍又一遍的做別人已經做過的東西。

如果你需要某些事項的原始碼，如果已經有某人做過的話，就向群組發email求助。結果會很驚喜哦！

在許多大的群組中，個人往往不知道其他人在幹什麼。你甚至可以發現某人在找一些東西做，並且自願為你寫程式碼，如果人們在一起工作，外面就總有一個金礦。

4.3. 告訴！當你在做事的時候，把它告訴所有人

如果你做了什麼可重用的東西的話，讓其他人知道。別害羞，也不要為了保護自豪感而把你的工作成果藏起來。一旦養成共享工作成果的習慣，每個人都會獲得更多。

4.4. 小型程式碼庫

對於程式碼重用，一個常見的問題就是人們不從他們做過的程式碼中做庫。一個可重用的類可能正隱蔽在一個程式目錄並且決不會有被分享的激動，因為程式設計師不會把類分拆出來加入庫中。

這樣的其中一個原因就是人們不喜歡做一個小庫，對小庫有一些不正確感覺。把這樣的感覺克服掉吧，電腦才不關心你有多少個庫呢。

如果你有一些程式碼可以重用，而且不能放入一個已經存在的庫中，那麼就做一個新的庫吧。如果人們真的考慮重用的話，庫不會在很長的一段時間裡保持那麼小的。

4.5. 知識庫

很多公司不清楚現有什麼程式碼可用，而且大多數程式設計師仍然沒有通過溝通他們已經做過了什麼，或者一直在詢問現存什麼程式碼可用。解決這個的方法是有一個可用的知識庫。

理想的情況是，程式設計師可以到一個WEB頁，瀏覽或者查詢打包的知識庫列表，找到他們所要的。建立一個程式設計師可以自動維護的知識庫系統，是一個很不錯的做法。如果有一個專門的管理員來負責維護這個知識庫，那當然更好。

另一種方法是自動的從程式碼中產生知識庫的做法。把通用的類、方法和標頭（subsystem headers）作為手冊或者是知識庫的一個條目。

5. 書寫註釋

5.1. 講一個故事

把你的註釋當作描述系統的一個故事。並且使得你的註釋能被機器解析後，以固定的格式放到手冊中去。類的註釋是故事的一部分，方法的名稱、方法的註釋、方法的實現也是故事一部分。所有的這些部分編織在一起，使得人們在以後的時間裡能夠準確的知道你幹了什麼，為什麼這麼做。

5.2. 歸檔註釋

註釋的要歸檔才有意義，否則，假如在一個地方放一條註釋描述你做了什麼選擇和你為什麼這麼做，只有考古學家才能發現這是最有用的資訊。（如何歸檔另行規範）

5.3. 註釋結構

工程的每部分都有特定的註釋結構。 程式中的註釋，這裡給出示例作為規範，註釋中以 * @
為關鍵字的開始，以:為註釋關鍵字結尾。

5.3.1. 預定義關鍵字

關鍵字 含義
Purpose
表示類、屬**、方法要做些什麼或者什麼含義。
Package Name 類名
Author 作者
Modifications
修改記錄（編號規則為“No”＋日期＋“－”＋序號）
See 參考
Method Name 方法名
Parameter 引數名（包括型別）

Return 返回值（包括型別）
Attribute/Variable Name 屬**/變數名
Type 屬**/變數型別

5.3.2. 類的註釋

/**
* @ Purpose:
* 訪問資料庫的類，以ODBC作為通用訪問介面

* @Package Name: Database
* @Author: Forrest Gump gump@crtvu.edu.cn

* @Modifications:
* No20020523-100:
*
odbc_fetch_into()引數位置第二和第三個位置調換
* John Johnson John@crtvu.edu.cn
* @See:
(參照)
*/
class Database
{
……
}

5.3.3. 方法註釋

/**
* @Purpose:
* 執行一次查詢
* @Method Name: Query()
*
@Parameter: string $queryStr SQL查詢字串
* @Return: mixed 查詢返回值（結果集物件）
*/

function（$queryStr）{……}

5.3.4. 屬**或變數註釋

/**
* @Purpose:

* 資料庫連線使用者名稱
* @Attribute/Variable Name: mDbUserName
* @Type: string

*/
var mDbUserName;

5.3.5. if (0)來註釋外部程式碼塊

有時需要註釋大段的測試程式碼，最簡單的方法就是使用if (0)塊：
function example()
{
great
looking code

if (0) {
lots of code
}

more code
}

你不能使用/**/，因為註釋內部不能包含註釋，而大段的程式中可以包含註釋。

5.3.6. 目錄文件

所有的目錄下都需要具有README文件，其中包括：
· 該目錄的功能及其包含內容
·
一個對每一檔案的線上說明（帶有link），每一個說明通常還應該提取檔案標頭的一些屬**名字。
· 包括設定、使用說明
·
指導人們如何連線相關資源：
o 原始檔索引
o 線上文件
o 紙文件
o 設計文件
· 其他對讀者有幫助的東西

考慮一下，當每個原有的工程人員走了，在6個月之內來的一個新人，那個孤獨受驚嚇的探險者通過整個工程的原始碼目錄樹，閱讀說明檔案，原始檔的標頭說明等等做為地圖，他應該有能力穿越整個工程。

6. 其他

· 採用物件導向的設計方法；

理由

毫無疑問這是最接近人們自然思維的方法，可能前期會覺得沒有直接書寫來得快，能否試著保留自己的看法？好戲在後頭！

·
類的定義採用一個檔案一個類，並且類名和檔名相同；

理由
o 越來越多的人接受了這種做法
o
事實證明這種方法使得專案的邏輯結構更清晰

· 類定義檔案中，定義體之外不得出現諸如echo、print等輸出語句；

理由

出現這樣的語句，應該當做出現bug來看。

· 輸出網頁的頁面不出現SQL語句

理由

這是n層結構的程式設計思想所致，每層的任務不同，雖然可以越權行使，可能這樣很快捷，但我們不贊成這麼幹。

·
進行SQL執行的資料必須進行有效**檢測

特殊符號：
對於MS SQL Server，’%_[ ]
這些符號都是在書寫SQL語句中的特殊含義字元，在SQL執行前需要對這些字元進行處理。
指令碼符號：

對於PHP指令碼標記，如<??><%%><?php?><script lang<script
language=”php”></script>，在進入資料庫前需要檢測處理。
理由

這是資料庫程式設計的一個約定，很多參考書上也是這麼說，這裡需要強調一下。

· 在HTML網頁中儘量不要穿插PHP程式碼

迴圈程式碼和純粹變數輸出（類似於<?=$UserName?>）除外。
理由
o
需要說明的是我們工作的上游，頁面設計者的工作，假如在頁面中穿插程式碼，將破壞結構，這應當是我們需要避免的。
o
在這裡的PHP程式碼只負責顯示，多餘的程式碼顯然是不應該的。

· 沒有含義的數字

一個在原始碼中使用了的赤裸裸的數字是不可思議的數字，因為包括作者，在三個月內，沒人它的含義。例如：
if (22 == $foo) {
start_thermo_nuclear_war(); }
else if (19 == $foo) { refund_lotso_money(); }

else if (16 == $foo) { infinite_loop(); }
else { cry_cause_im_lost(); }

在上例中22和19的含義是什麼呢？如果一個數字改變了，或者這些數字只是簡單的錯誤，你會怎麼想？

使用不可思議的數字是該程式設計師是業餘運動員的重要標誌.

你應該用define()來給你想表示某樣東西的數值一個真正的名字，而不是採用赤裸裸的數字，例如：

define(“PRESIDENT_WENT_CRAZY”, “22”);
define(“WE_GOOFED”, “19”);

define(“THEY_DIDNT_PAY”, “16”);

if (PRESIDENT_WENT_CRAZY == $foo) {
start_thermo_nuclear_war(); }
else if (WE_GOOFED == $foo) {
refund_lotso_money(); }
else if (THEY_DIDNT_PAY == $foo) { infinite_loop();
}
else { happy_days_i_know_why_im_here(); }
現在不是變得更好了麼？

7.
PHP副檔名

常見的PHP檔案的副檔名有：html, .php, .php3, .php4, .phtml, .inc,
.class…
這裡我們約定：

· 所有瀏覽者可見頁面使用.html
· 所有類、函式庫檔案使用.php

理由

· 副檔名描述的是那種資料是使用者將會收到的。PHP是解釋為HTML的。

8. PHP程式碼標記

統一使用<?php ?>，只輸出變數時<?=$username?>