著作權屬於原創所有。。。。。。。。。。。。。。。。
[轉]PHP編碼規範
比較詳細的講解了在程式編寫中要注意的問題。
但規範只是一種習慣，而不是一種強制性的東西，你完全可以不服從它。但養成良好的代碼書寫習慣，
個人認為還是很有必要的
PHP 編碼規範
原文：http://pear.php.net/manual/en/standards.php
翻譯：廖宇雷
最後更新日期：2003/05/06
內容列表
縮排
控制結構
函數調用
函數定義
注釋
包含代碼
PHP 代碼標記
頭註解區塊
使用 CVS
例子 URLs
命名規範
--------------------------------------------------------------------------------
縮排
縮排使用4個空格，而不是 tab。如果你使用 Emacs 編輯 PEAR 代碼，你應該設定 indent-tabs-mode
為 nil。下面是一個 mode hook 的樣本，用於設定 Emacs 符合縮排標準（你必須確保在編輯 PHP 檔案
時，這些設定發生作用）：
(defun php-mode-hook ()
(setq tab-width 4
c-basic-offset 4
c-hanging-comment-ender-p nil
indent-tabs-mode
(not
(and (string-match "/(PEAR|pear)/" (buffer-file-name))
(string-match ".php$" (buffer-file-name))))))
這裡是同等效果的 vim 規則：
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4
--------------------------------------------------------------------------------
控制結構
控制結構包含 if、for、while、switch 等。這裡有一個 if 語句的樣本和一個 switch 語句的樣本：
if 語句的樣本：
| CODE: |
[Copy to clipboard] |
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
?> |
|
switch 語句的樣本：
| CODE: |
[Copy to clipboard] |
switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
?> |
|
控制語句應該在控制關鍵詞和開始的圓括弧之間應該有一個空格，以此和函數調用進行區別。
強烈建議你總是使用花括弧將控制結構各部分標識出來。即使是在技術上可以不使用花括弧的地方。這
可以增加代碼的可讀性，同時避免在結構部分增加新行後引入邏輯上的錯誤。
原始代碼：
| CODE: |
[Copy to clipboard] |
if (condition)
return true;
else
return false; |
|
修改後的代碼：
| CODE: |
[Copy to clipboard] |
if (condition)
do something; // 出現邏輯錯誤
return true;
else
return false; |
|
正確的做法：
| CODE: |
[Copy to clipboard] |
if (condition) {
do something;
return true;
} else {
return false;
} |
|
--------------------------------------------------------------------------------
函數調用
調用函數時，函數名和開始的括弧之間不應該有空白字元。參數和開始及結束的括弧之間不應有空格。
而除第一個參數外，其他參數都應該用一個空格分隔。這裡有一個樣本：
| CODE: |
[Copy to clipboard] |
$var = foo($bar, $baz, $quux);
?> |
|
像上面的範例程式碼，賦值運算等號兩邊都應該使用一個空格。如果是相關的賦值運算，應該採用下面的
形式以提供更好的可讀性：
| CODE: |
[Copy to clipboard] |
$short = foo($bar);
$long_variable = foo($baz);
?> |
|
--------------------------------------------------------------------------------
函數定義
按照“one true brace”約定聲明函數：
| CODE: |
[Copy to clipboard] |
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
?> |
|
“one true brace”約定就是開始的花括弧單獨佔一行，而不是跟在其他語句後面。
具有預設值的參數應該位於參數列表的後面（事實上 PHP 語言定義也要求如此）。如果適合，函數應該
總是返回一個有意義的值。這裡有一個稍微長一點的樣本：
| CODE: |
[Copy to clipboard] |
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
?> |
|
--------------------------------------------------------------------------------
注釋
類型（class）的聯機文檔應該符合 PHPDoc（類似於 JavaDoc）的約定。更多關於 PHPDoc 的資訊可以
訪問 http://www.phpdoc.de/ 獲得。
此外，強烈鼓勵使用非文檔注釋。一般性規則是對於那些容易忘記作用的代碼添加簡短的介紹性注釋。
推薦使用 C 樣式的注釋（/* */）和標準 C++ 注釋（//)，而不應該使用 Perl/shell 樣式的注釋（#）。
--------------------------------------------------------------------------------
包含代碼
無論在什麼地方無條件包含一個類型檔案，應該使用 require_once()。如果有條件的包含一個類型檔案
（例如使用Factory 方法），應該使用 include_once()。使用兩者中的任何一個都能夠確保類型檔案只包含
一次。它們共用一個檔案清單，因此你不需要擔心混淆他們 ?? 一個檔案使用 require_once() 包含
後不會在 include_once() 中再一次被包含。
備忘：include_once() 和 require_once() 是一個聲明，而不是函數。你不需要使用圓括弧將檔案名稱擴
起來（不過使用括弧也不會出現錯誤）。
--------------------------------------------------------------------------------
PHP 代碼標記
總是使用 來界定 PHP 代碼，而不要使用 速記方式。這是為了符合 PEAR 一致性所必
須的，同時也是在不同作業系統和不同安裝設定環境下移植 PHP 代碼所要求的。
--------------------------------------------------------------------------------
頭註解區塊
PEAR 發布的所有原始碼檔案頭部都應該包含下面的註解區塊：
| CODE: |
[Copy to clipboard] |
/* vim: set expandtab tabstop=4 softtabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | PHP version 4 |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997-2002 The PHP Group |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | that is bundled with this package in the file LICENSE, and is |
// | available at through the world-wide-web at |
// | http://www.php.net/license/2_02.txt. |
// | If you did not receive a copy of the PHP license and are unable to |
// | obtain it through the world-wide-web, please send a note to |
// | license@php.net so we can mail you a copy immediately. |
// +----------------------------------------------------------------------+
// | Authors: Original Author |
// | Your Name |
// +----------------------------------------------------------------------+
//
// $ Id $
?> |
|
這裡沒有硬性規定要將一個代碼貢獻者的名字添加到檔案注釋的作者列表中。一般情況下，他們的更改
屬於“substantial”目錄（意味大約10%到20%的代碼被改寫）。有一個例外就是代碼貢獻者重寫了函數
或者貢獻了新的程式邏輯。
簡單的代碼重組和 bug 修複不應該增加新作者，這是不恰當的。
不在核心 PEAR 倉庫中的檔案應該有一個類似的註解區塊來說明著作權、許可協議和作者。所有檔案應該包
含一個模式行（modeline，用於 vim 和 emacs）以確保一致性。
--------------------------------------------------------------------------------
使用 CVS
這個小節的內容僅僅適用於 cvs.php.net 上使用 CVS 的包。
在每一個檔案中包含 $Id $（兩個 $ 符號之間的關鍵字不能夠有空格，但由於此文檔也是用 CVS 管理
，因此只好加個空格，避免被 CVS 替換掉） CVS 關鍵字，以便查看檔案目前狀態和最後修改時間等信
息。如果已經存在“Last Modified:”這樣的資訊，則替換為 $Id $ 標記。
這個小節的其他內容假定你有關於 CVS 標記和分支（branches）的基本知識。
CVS 標記用於標識你包中的檔案釋放之前所作的修訂。下面的列表是必需使用和建議使用的 CVS 標記：
RELEASE_n_n
（必需的）用於標記一個釋放版本。如果你沒有使用這個標記，別人就沒有辦法在你發布一個釋放版本
時從 CVS 伺服器擷取你的包。
QA_n_n
（分支，可選）如果你覺得在發布釋放版本之前要提供一個候選釋放版本，那麼一個好主意就是增加一
個分支。這個分支可以讓你將釋放版本隔離出來，並在正式發布釋放版本之前可以為這些分支單獨應用
更新。期間，正常的開發工作可以在主幹上繼續進行。
MAINT_n_n
（分支，可選）如果你需要建立一個較小修改的釋放版本（例如在 1.2 之後發布 1.2.1）。那麼你可以
建立一個分支來達到目的。
僅有 RELEASE 標記是必須的，其他標記為了方便推薦你使用。
下面是一個如何為 "Money_Fast" 包 1.2 釋放版本增加標記的樣本：
$ cd pear/Money_Fast
$ cvs tag RELEASE_1_2
T Fast.php
T README
T package.xml
經過上面的操作，就可以在 PEAR Web 網站上擷取你的一系列釋放版本了。
這裡是一個如何建立 QA 分支的樣本：
$ cvs tag QA_2_0_BP
...
$ cvs rtag -b -r QA_2_0_BP QA_2_0
$ cvs update -r QA_2_0
$ cvs tag RELEASE_2_0RC1
...and then the actual release, from the same branch:
$ cvs tag RELEASE_2_0
"QA_2_0_BP" 標記是一個 "branch point" 標記，用於標記分支的開始。總是用這樣的標記來標明分支
的開始是一個好主意。MAINT 分支可以使用 RELEASE 標記作為它的分支起點。
--------------------------------------------------------------------------------
樣本中的 URL
所有樣本中用到的 URL 地址都應該是 "example.com"、"example.org"、"example.net"。
--------------------------------------------------------------------------------
命名規範
一般而言，class、函數和變數的名字應該總是能夠描述讓代碼閱讀者能夠容易的知道這些代碼的作用。
Classes
class 應該具有一個描述性的名字。可能時應該避免使用縮寫。class 名字應該總是用一個大寫字母開
始。從 class 名字中也能夠反映出 PEAR class 的層次。層次中的每個層級都用底線進行分隔。好的
class 名字樣本如下：
Log
Net_Finger
HTML_Upload_Error
函數和方法
函數和方法應該使用 "studly caps" 樣式命名。函數應該將所在包的名字作為首碼，以避免與其他包的
函數發生名字衝突。名字的受字母（首碼之後）應該是小寫，每一個新單詞應該以大寫字母開頭。下面
是一些樣本：
connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()
私人 class 成員和屬性（意味著 class 成員和屬性只應該由同一個 class 中聲明的成員使用。不過
PHP 並不支援強制性的私人命名空間）應該用一個底線開頭。樣本：
_sort()
_initTree()
$this->_status
常數
常數應該總是全部使用大寫字母命名，用底線來分隔單詞。常數名字的首碼應該使用大寫的 class/包
名字。例如：DB:: 包使用的所有常數都已 DB_ 開頭。
全域變數
如果你的包需要定義全域變數，那麼應該用底線跟上包的名字和另一個底線作為開頭。例如，PEAR
包使用一個全域變數名為 $_PEAR_destructor_object_list。
預定義的值 true、false 和 null
PHP 的內建值 true、false 和 null 必須全部用小寫字母書寫。
