php編碼規范 · MuuCmf T5 完全開發手冊

[TOC] ### 編碼規范 ### 前言如果您已經決定向加入微擎社區并貢獻代碼，請詳細閱讀以下規范，并嚴格遵守。本規范由編程原則組成，融合并提煉了開發人員長時間積累下來的成熟經驗，意在幫助開發者養成良好一致的編程風格。如果有需要,本文檔會不定期更新。 ### 標準化的重要性和好處當一個軟件項目嘗試著遵守公共一致的標準時，可以使參與項目的開發人員更容易了解項目中的代碼、弄清程序的狀況。使新的參與者可以很快的適應環境，防止部分參與者出于節省時間的需要，自創一套風格并養成終生的習慣，導致其他人在閱讀時浪費過多的時間和精力。而且在一致的環境下，也可以減少編碼出錯的機會。缺陷是由于每個人的標準不同，所以需要一段時間來適應和改變自己的編碼風格，暫時性的降底了工作效率。從使項目長遠健康的發展以及后期更高的團隊工作效率來考慮暫時的工作效率降低是值得的，也是必須要經過的一個過程。標準不是項目成功的關鍵，但可以幫助我們在團隊協作中有更高的效率并且更加順利的完成既定的任務。 * 程序員可以了解任何代碼，弄清程序的狀況 * 新人可以很快的適應環境 * 防止新接觸微擎的開發人員出于節省時間的需要，自創一套風格并養成終生的習慣 * 防止新接觸PHP或微擎的開發人員一次次的犯同樣的錯誤 * 在一致的環境下，開發人員們可以減少犯錯的機會 * 程序員們有了一致的敵人 ### PHP編碼規范與原則 #### 文件編碼及編輯器格式請在開始編輯MuuCmf代碼之前調整你的編輯器設置。 **本條規范同樣適用于 PHP、HTML、CSS、JavaScript** ##### **編碼** 請調整您的編輯器文件編碼為 UTF-8，并關閉 UTF-8 BOM((Byte Order Mark))的功能。**切記請不要使用windows自帶的記事本編輯項目文件。** *注意：請確認你的編輯器不會有意或無意的保存文件為 UTF-8 BOM 格式，否則可能造成微擎系統通信不正常。* ##### **縮進** 每個縮進的單位約定是一個Tab(禁止設置為空格替代，Tab寬度應表示為4個空白字符寬度)，需每個參與項目的開發人員在編輯器(UltraEdit、EditPlus、ZendStudio等)中進行強制設定，以防在編寫代碼時遺忘而造成格式上的不規范。 ##### **換行** Muu項目中使用Unix風格的換行符，即只有換行( LF 或 "\\n" )沒有回車( CR 或 "\\r" )，請在你的編輯器內調整 #### 代碼標記 PHP程序需使用來界定 PHP 代碼，在HTML頁面中嵌入純變量時，可以使用這樣的形式。 *注意：為了使代碼規范化和標準化，Muu開發中禁止使用和這種速記形式。* ##### **注釋** 注釋是對于那些容易忘記作用的代碼添加簡短的介紹性內容。請使用 C 樣式的注釋“/\* \*/”和標準 C++ 注釋“//”。開發留下的臨時代碼和調試代碼必須添加注釋，以免日后遺忘。所有臨時性、調試性、試驗性的代碼，必須添加統一的注釋標記“//debug”并后跟完整的注釋信息，這樣可以方便在程序發布和最終調試前批量檢查程序中是否還存在有疑問的代碼。例如： ~~~ $num = 1; $flag = true; //debug 這里不能確定是否需要對$flag進行賦值 if(empty($flag)) { //Statements } ~~~ #### 書寫規則 ##### **大括號{}、if和switch** * 首括號與關鍵詞同行，尾括號與關鍵字同列； * if 結構中，else 和 elseif 與前后兩個大括號同行，左右各一個空格。另外，即便 if 后只有一行語句，仍然需要加入大括號，以保證結構清晰； * switch 結構中，通常當一個 case 塊處理后，將跳過之后的 case 塊處理，因此大多數情況下需要添加 break。break 的位置視程序邏輯，與 case 同在一行，或新起一行均可，但同一 switch 體中，break 的位置格式應當保持一致。以下是符合上述規范的例子： ~~~ if ($condition) { //Statements } else { switch ($str) { case 'abc': $result = 'abc'; break; default: $result = 'unknown'; break; } } ~~~ ##### **運算符、小括號、空格、關鍵詞和函數** * 每個運算符與兩邊參與運算的值或表達式中間要有一個空格； * 左括號“(” 應和函數關鍵詞緊貼在一起，除此以外應當使用空格將“(”同前面內容分開； * 右括號“)”除后面是“)”，其他一律用空格隔開它們； * 除字符串中特意需要，一般情況下，在程序以及HTML中不出現兩個連續的空格； * 任何情況下，PHP程序中不能出現空白的帶有TAB或空格的行，即：這類空白行應當不包含任何TAB或空格。同時，任何程序行尾也不能出現多余的TAB或空格； * 每段較大的程序體，上、下應當加入空白行，兩個程序塊之間只使用1個空行，禁止使用多行。 * 程序塊劃分盡量合理，過大或者過小的分割都會影響他人對代碼的閱讀和理解。一般可以以較大函數定義、邏輯結構、功能結構來進行劃分。少于15行的程序塊，可不加上下空白行； * 說明或顯示部分中，內容如含有中文、數字、英文單詞混雜，應當在數字或者英文單詞的前后加入空格。根據上述原則，以下舉例說明正確的書寫格式： ~~~ $result = (($a + 1) * 3 / 2 + $num)) . 'Test'; $condition ? func1($var) : func2($var); $condition ? $long_statement : $another_long_statement; if ($flag) { //Statements //More than 15 lines } showmessage('請使用 restore.php 工具恢復數據。'); ~~~ ##### **函數定義** * 函數的命名采用小寫字母+下劃線構成；如：get_user_id() * 參數的名字和變量的命名規范一致； * 函數定義中的左小括號換行，與函數名緊挨，中間無需空格； * 開始的左大括號與函數定義起新行； * 具有默認值的參數應該位于參數列表的后面； * 函數調用與定義的時候參數與參數之間加入一個空格； * 必須仔細檢查并切實杜絕函數起始縮進位置與結束縮進位置不同的現象；例如，符合標準的定義： ~~~ function message($string, $operation, $key = '') { if ($flag) { //Statement } //函數體 } ~~~ 不符合標準的定義： ~~~ function authcode($string,$operation,$key = ''){ //函數體 } ~~~ ##### **引號** 由于PHP中單引號和雙引號具有不同的含義，因此在使用時有如下原則： * 在能使用單引號的情況下，禁止使用雙引號。 * 字符串為固定值,不包含換號、制表等特殊轉義時，需使用單引號。 * 字符串作為數據索引時，需使用單引號。 * 字符串不需要帶入變量，需使用單引號。 * 數據庫SQL語句一律使用雙引號，SQL語句中所有數據必須加單引號，無論數值還是字串，以避免可能的注入漏洞和SQL錯誤。 ~~~ $sql = "UPDATE " . tablename('members') . " SET adminid='1' WHERE AND adminid='2'"; ~~~ #### 數據庫操作 #### 命名原則命名是程序規劃的核心。古人相信只要知道一個人真正的名字就會獲得凌駕于那個人之上的不可思議的力量。只要你給事物想到正確的名字，就會給你以及后來的人帶來比代碼更強的力量。名字就是事物在它所處的生態環境中一個長久而深遠的結果。總的來說，只有了解系統的程序員才能為系統取出最合適的名字。如果所有的命名都與其自然相適合，則關系清晰，含義可以推導得出，一般人的推想也能在意料之中。就一般約定而言，類、函數和變量的名字應該總是能夠描述讓代碼閱讀者能夠容易的知道這些代碼的作用。形式越簡單、越有規則，就越容易讓人感知和理解。應該避免使用模棱兩可，晦澀不標準的命名。 ##### **變量、函數名** * 變量、函數名一律為小寫格式； * 以標準計算機英文為藍本，杜絕一切拼音、或拼音英文混雜的命名方式； * 變量命名只能使用項目中有據可查的英文縮寫方式，例如可以使用 $data 而不可使用 $data1、$data2 這樣容易產生混淆的形式，應當使用 $trade、$product 這樣一目了然容易理解的形式； * 可以合理的對過長的命名進行縮寫，例如 $bio($biography)，$tpp($threadsPerPage)，前提是英文中有這樣既有的縮寫形式，或字母符合英文縮寫規范； * 必須清楚所使用英文單詞的詞性，在權限相關的范圍內，大多使用 $allowXxx 或 $isXxx 的形式，前者后面接動詞，后者后面接形容詞。 * 變量名標識符不應當使用下劃線“\_”進行分割，函數名根據需要可按照模塊單元名稱使用下劃線添加前綴，以實現命名空間的效果。但每個函數名標識符盡量避免出現三個以上的下劃線。 ##### **類和接口名** * 類和接口的命名采用混合大小寫字母的Pascal命名法 * 具體描述為：首字母大寫，后續的每個單詞也需要大寫首字母。如：MySQLConnector、CacheProvider。 * 接口的命名與類相似，但需要以大寫字母“I”開頭，以作區分。 * 對象成員的命名則采用混合大小寫字母的Camel命名法 * 具體描述為：公有成員及保護成員應首字母小寫，后續的每個單詞首字母大寫 * 私有成員除需保持共有成員的命名方式外，還需要以下劃線“\_”開頭，以作區分。 ##### **JavaScript代碼** * JavaScript中類和全局對象應使用混合大小寫字母的Pascal命名法 * 具體描述為：首字母大寫，后續的每個單詞也需要大寫首字母。如：MySQLConnector、CacheProvider。 * JavaScript中變量、函數名應采用混合大小寫字母的Camel命名法。 * 具體描述為首字母小寫，后續的每個單詞首字母大寫 ##### **常量** * 常量應該總是全部使用大寫字母命名，必要的情況下，可使用劃線來分隔單詞； * PHP 的內建值 true、false 和null必須全部采用小寫字母書寫。 #### 變量的初始化與邏輯檢查任何變量在進行累加、直接顯示或存儲前必需進行初使化 ,例如： ~~~ $number = 0; // 數值型初始化 $string = ''; // 字符串初始化 $array = array(); // 數組初始化 ~~~ * 判斷一個無法確定（不知道是否已被賦值）的變量時，可用empty()或isset()，而不要直接使用if($switch)的形式。 * empty()和isset()的區別為：請參閱PHP手冊。 * 如果已經使用 unset() 釋放了一個變量之后，它將不再是 isset()。若使用 isset() 測試一個被設置成 NULL 的變量，將返回 FALSE。同時要注意的是一個 NULL 字節（"\\0"）并不等同于 PHP 的 NULL 常數。 * 判斷一個變量是否為數組，請使用is\_array()，這種判斷尤其適用于對數組進行遍歷的操作，例如foreach()，因為如果不事先判斷，foreach()會對非數組類型的變量報錯； * 判斷一個數組元素是否存在，可使用isset($array\['key'\])，也可使用empty()。 #### 安全性 * PHP中的變量不并不像C語言那樣需要事先聲明，解釋器會在第一次使用時自動創建他們，同樣類型也不需要指定，解釋器會根據上下文環境自動確定。從開發人員的角度來看，這無疑是一種極其方便的處理方法。一個變量被創建了，就可以在程序中的任何地方使用。這導致的結果就是開發人員工經常不注意初始化變量。因此，為了提高程序的安全性，我們不能相信任何沒有明確定義的變量。所有的變量在定義使用前要初使化以防止惡意構造提交的變量覆蓋程序中使用的變量。 * 不要相信任何客戶端提交的數據是安全的。（包括:$\_GET、$\_POST、$\_COOKIE、$\_FILES、$\_SERVER、$\_REQUEST） #### 其他細節問題 ##### **包含調用** * 包含調用程序文件，請盡量使用require，以保證效率。必要情況下，如難以避免的重復調用時可以使用require\_once。 * 包含調用緩存文件，由于緩存文件無法保證100%正確打開，請使用 include\_once 或 include。在必要時，可以使用 @include\_once 或 @include 的方式，以忽略錯誤提示； * 包含和調用代碼中，須以 IA\_ROOT . '/'開頭，應避免直接寫程序文件名(例如：require\_once 'x.php';)的做法； * 所有被包含和調用的程序文件，包括但不限于程序、緩存或模板，通常其不能被直接URL請求。程序通過在 IA\_ROOT/source/bootstrap.inc.php中定義一個標記性常量IN\_IA，來判斷程序是否被合法調用。因此，在除了IA\_ROOT/source/bootstrap.inc.php以外的任何一個被包含和調用的程序文件中，需要包含以下內容，以使得訪問者無法直接通過URL請求該文件： `if (!defined('IN_IA')) { exit('Access Denied'); }` ##### **錯誤報告級別** * 在軟件開發和調試階段，修改 /data/config.php 中的 $config\['setting'\]\['development'\] = 1;，打開錯誤報告以便能夠報告程序中所有的錯誤、警告和提示信息，以幫助開發者檢查和核對代碼，避免大多數安全性問題和邏輯錯誤、拼寫錯誤。 * 在軟件發布時，請修改 /data/config.php 中的 $config\['setting'\]\['development'\] = 0;，來關閉錯誤報告，以利于用戶使用并將無謂錯誤提示信息降至最低。 ##### **其他注意要點** * 正則表達式操作請使用perl兼容正則表達式，即preg\_ 系列的函數。以提升效率。 * 盡量使用高版本的函數。 * 本項目不使用命名空間，因此需要按照傳統的方式使用文件名和文件夾來規劃代碼結構。 ### 數據庫設計 #### 表和字段命名 * 表和字段的命名以[PHP編碼中的命名規范](http://www.hmoore.net/donknap/we7/134620)為基本準則。 * 所有數據表名稱，只要其名稱是可數名詞，則必須以復數方式命名，例如：ims\_members(用戶表)、ims\_rules(規則定義表)； * 存儲多項內容的字段，或代表數量的字段，也應當以復數方式命名，例如：params(parameters，參數個數)、views(查看次數)、replies(回復次數)。 * 當幾個表間的字段有關連時，要注意表與表之間關聯字段命名的統一，如 ims\_rule\_keywords表中的rid與ims\_rules表中的rid。代表id自增量的字段，通常用以下幾種形式： * 最常用的核心id，或經常在URL中進行調用的，盡量用簡寫的形式，例如rid、weid、uid； * 有功能性作用，URL中偶爾用到的id，使用全稱的形式，例如pluginid； * 沒有功能性作用，只為管理和維護方便而設的id，可以使用全稱的形式，也可只將其命名為id。所有與表、字段相關的命名，請參考微擎系統現有字段的命名方式，以保證命名的系統性和統一性。 #### 字段結構 * 基于效率的考慮，所有字段均不能為空，即全部NOT NULL，可以設置默認值來代替。 * 預計不會存儲非負數的字段，例如各項id、統計數等，必須設置為UNSIGNED類型。UNSIGNED類型比非UNSIGNED類型所能存儲的正整數范圍大一倍，因此能獲得更大的數值存儲空間。 * 儲開關、選項數據的字段，通常使用tinyint(1)非UNSIGNED類型，少數情況也可能使用enum()結果集的方式。tinyint作為開關字段時，通常1為打開；0為關閉；-1為特殊數據，例如N/A(不可用)，高于1的為特殊結果或開關二進制數組合。 * 任何類型的數據表，字段空間應當本著足夠用，不浪費的原則。MEMORY/HEAP類型的表中，尤其要注意規劃節約使用存儲空間，這將節約更多內存。 #### SQL語句 * 所有SQL語句中，除了表名、字段名稱以外，全部語句和函數均需大寫，應當杜絕小寫方式或大小寫混雜的寫法。例如select \* from ims\_members;是不符合規范的寫法。 * 很長的SQL語句應當有適當的斷行，依據JOIN、FROM、ORDER BY等關鍵字進行界定。 * 通常情況下，在對多表進行操作時，要根據不同表名稱，對每個表指定一個1~2個字母的縮寫，以利于語句簡潔和可讀性。 * 參考[PHP編碼規范中的數據庫操作指南](http://www.hmoore.net/donknap/we7/134620) #### 運算與檢索 * 數值運算一般比字符串運算更快。例如比較運算，可在單一運算中對數進行比較。而串運算涉及幾個逐字節的比較，如果串更長的話，這種比較還要多。 * 如果串列的值數目有限，應該利用普通整型或emum類型來獲得數值運算的優越性。 * 更小的字段類型永遠比更大的字段類型處理要快得多。對于字符串，其處理時間與串長度直接相關。一般情況下，較小的表處理更快。對于定長表，應該選擇最小的類型，只要能存儲所需范圍的值即可。例如，如果mediumint夠用，就不要選擇bigint。對于可變長類型，也仍然能夠節省空間。一個TEXT 類型的值用2 字節記錄值的長度，而一個LONGTEXT 則用4字節記錄其值的長度。如果存儲的值長度永遠不會超過64KB，使用TEXT 將使每個值節省2字節。 #### 性能優化主要分為：表結構優化，索引優化，查詢優化。取決于開發人員經驗和個人能力。不詳述。 ### 模板及界面設計原則 #### 標記及界面書寫規則 ##### **模板標記**#### * 模板方案采用通用的PHP編譯模板方案，模板標記為`<!—{}-->或{}，建議使用加入注釋的模板標記<!—{}-->`，這樣可以使得模板可讀性更好。 * 在HTML標記中使用的邏輯體無需使用HTML注釋`()，即<input type=”text”{if xxx} value=”1”{/if} />` ##### **HTML** * 所有HTML標記參數賦值需使用雙引號包含，例如，應當使用`<input type=”text” name=”test” value=”ok” />`，而絕對不能使用`<input type=text name=test value=ok />。` * 開始標記和結束標記必須成對出現 * 所有標記名稱，屬性名稱，CSS必須全部小寫 * HTML元素要求盡量指定title，以利于SEO。 * 盡量避免使用可視化編輯工具通過拖拽進行撰寫或修改，可能會因此造成界面錯亂 ##### **變量** * 模板中使用的變量，依據作用和出現位置不同，分為幾種方式： * 邏輯體中，即被 { } 包圍起來的部分，例如 {if isset($array\['key'\])} 這種形式，其中的變量書寫規范與PHP程序中完全一致； * 模板內容中，直接輸入的變量內容，需要使用 {} 將變量括起來，以免出現模板編譯錯誤； * 直接輸入內容為數組的，需要加單引號“'”來講索引包括起來。如下： * 數組的下標為變量的，正確的寫法為{$trade\['details'\]\['title'\]}； * 其他變量十分復雜的情況，為保證兼容性。應使用 {php echo $var;}。如：{php echo (!empty($row\['dateline'\]) ? date('Y-m-d', $row\['dateline'\]) : '');} ##### **縮進** * 在微擎系統的\*.html模板文件中，應盡量按照HTML本身的縮進風格縮進，另外如果存在邏輯語句，邏輯語句也應該保持對應的縮進結構。縮進采用TAB方式，不使用空格作為縮進符號。例如： ~~~  <table class="tb"> <tr> <td>{$trade[username]}</td> </tr> </table>  ~~~ #### CSS書寫規則樣式表書寫應該遵循以下原則： * 編碼方式要求采用utf-8，即： * CSS盡量使用外部鏈接方式，盡可能壓縮CSS文件的數量，盡可能的避免使用行內樣式。 * 分區域注釋。 * CSS定義不要使花括號換行。 * 類，ID命名原則：CSS命名應全部采用小寫字母，多個單詞間應使用連字符“-”鏈接。應遵循通用的CSS命名習慣：header，content，container，footer，column，message，btn等等。 * 結構化設計CSS * 標識類圖片，應該使用CSS Spirit方案解決（即：CSS貼圖定位），以盡量減少請求開銷，增強用戶體驗。 * 切圖命名，應該按照圖片作用，或者圖片位置等來命名，盡量做到見名知意。命名原則同CSS類，ID命名 #### JavaScript 書寫規則腳本書寫應該遵循以下原則： * 編碼方式要求采用utf-8； * 縮進及代碼格式應與[PHP編碼書寫規則](http://www.hmoore.net/donknap/we7/134620)相同； * 結構化設計JavaScript #### **文件及目錄** #### 文件命名 * 所有包含PHP代碼的程序文件或半程序文件，應以小寫.php作為擴展名，而不要使用.phtml、.php3、.inc、.class等作為擴展名。 * 目錄中如果包含多個詞組，用中橫線（-）分隔 ##### **普通程序** 能夠被URL直接調用的程序，例如home.php、index.php、forum.php，直接使用程序名+.php的方式命名 ##### **模板源文件** 以小寫.html作為擴展名。模板源文件按照[微擎模板機制](http://www.hmoore.net/donknap/we7/134620)編碼規則進行編寫，不是可以執行的程序，而只能被微擎模板模板編譯器所解析。 #### 空目錄索引 * 請在所有不包含普通程序(即能夠被URL直接調用的程序)的目錄中放置一個1字節的index.html文件，內容為一個空格。幾乎除Muu系統根目錄以外，所有目錄都屬于這一類型，因此開發者需要在這些目錄全部放入空index.html文件，以避免當http服務器的Directory Listing打開時，服務器文件被索引和列表。 * 附件目錄等敏感目錄，要在程序中實現相應功能，當新建下級目錄時，必須自動寫入一個空的index.html文件，以避免新建目錄被索引的問題。