差異處

這裏顯示兩個版本的差異處。

連向這個比對檢視

兩邊的前次修訂版 前次修改
下次修改		 前次修改
tech:mantis_coding [2009/03/03 01:04] – jonathantech:mantis_coding [2015/10/08 13:09] (目前版本) – [- 程式碼編輯工具應該有的特點] jonathan
行 1: 行 1:
 +====== php 程式碼撰寫標準規則 ======
 +  * 主要參考的 Mantis 程式碼撰寫標準網址 : http://www.mantisbt.org/guidelines.php
  
 +===== - 變數命名規則 =====
 +    * 變數名稱完全採用小寫英文字母.
 +    * 字與字之間使用 _ 來連接, 例如. $green_color_value
 +    * 要使用描述性的命名方式 (迴圈變數可以例外).
 +    * 迴圈變數通常使用: $i, $j, $k, ...等等.
 +    * 計算性的變數($bug 的總數)應以被計算的變數名稱($bug)後面接 _count 的格式來命名, 例如. $bug_count
 +    * 全域性的變數前面應該加上 g_
 +    * 存放 session 的變數前面應該加上 sess_
 +    * 存放 cookie 的變數前面應該加上 cookie_
 +    * 臨時(temp)的變數前面應該加上 t_
 +    * 由網頁表單傳過來的參數和變數如果已經確認不含 SQL 特殊字元(例如 /) 前面應該加上 c_
 +    * 由網頁表單傳過來的函式參數如果不確認是否含 SQL 特殊字元(例如 /), 那前面應該加上 p_
 +    * 由網頁表單傳過來的變數如果不確認是否含 SQL 特殊字元(例如 /), 那前面應該加上 f_
 +    * 其他的變數前面應該加上 v_, v2_, ...等等.
 +    * 為了避免視覺上的混淆, 變數前面千萬不要加上 l_ 或 o_ 或 q_ .
 +    * $query 和 $result 這兩個變數只能用在 SQL 的查詢語法變數($query)與查詢結果變數($result)
 +
 +
 +===== - 常數命名規則 =====
 +    * 常數名稱完全採用大寫英文字母.
 +    * 字與字之間使用 _ 來連接, 例如. ROOT_PATH
 +    * 全域性的常數前面應該加上 G_
 +    * 如果內容有可能會改變(例如在管理介面提供更改設定內容值), 應改採用變數而非常數
 +
 +
 +===== - 函式(Functions)命名規則 =====
 +
 +    * 函式名稱完全採用小寫英文字母.
 +    * 字與字之間使用 _ 來連接, 例如. setup_page_breaks()
 +    * 函式名稱不應該超過五個有意義的英文字, 例如. setup_page_from_old_to_new() -> setup_page_old_to_new()
 +    * 列印功能的函式前面應該要加上 print_, 例如. print_page()
 +    * 要儘量將功能有相關的函式加上相同的前置文字(可容易看出是相同群組的函式) 例如. email_, news_, ... 等等.
 +
 +
 +
 +
 +===== - Classes 命名規則 =====
 +
 +    * 要採用 FirstLetterOfWordIsCaptilized 的樣式
 +    * 屬於 class 物件內的變數, 前面應該要加上 m_
 +
 +
 +
 +
 +
 +===== - 檔案命名規則 =====
 +
 +    * 檔案名稱完全採用小寫英文字母.
 +    * 字與字之間使用 _ 來連接, 例如. view_new_bugs_page.php
 +    * 要使用 .php 當副檔名
 +    * 檔名長度必須小於 32 個字元. 這樣才能相容一些較舊的檔案系統像是 Mac OS.
 +    * 會被 Included 的檔案在檔名後面必須是 _inc.php
 +    * 預設的參數檔案在檔名後面加上 .default 例如. config_inc.php.default
 +
 +
 +===== - SQL 格式 =====
 +
 +    * 所有 SQL 的關鍵字必須採用大寫英文字母:
 +<code php>
 +      $query = "SELECT *
 +      FROM $g_mantis_bug_table
 +      WHERE id='1'";
 +</code>
 +    * 要以 $query 這特殊變數來存放 SQL 的命令. 這樣當發生錯誤時可以很容易找出問題的地方.
 +    * SQL 的寫法要分行, 這樣才能讓程式碼變的容易閱讀與了解.
 +
 +
 +
 +
 +
 +
 +
 +===== - 一般通用格式 =====
 +
 +    * 使用 TABS 來分出層次
 +<code php>
 +:
 +<TAB>if ( is_array( gpc_get( 'show_category', null ) ) ) {
 +<TAB><TAB>$f_show_category = gpc_get_string_array( 'show_category', META_FILTER_ANY );
 +<TAB>} else {
 +<TAB><TAB>$f_show_category = gpc_get_string( 'show_category', META_FILTER_ANY );
 +<TAB><TAB>$f_show_category = array( $f_show_category );
 +<TAB>}
 +:
 +</code>
 +    * 在 php 程式碼前後要以 <?php ?> 這樣式來撰寫
 +<code php>
 +:
 +<?php require_once( 'core.php' ) ?>
 +<?php auth_ensure_user_authenticated() ?>
 +<?php
 +        $f_type = gpc_get_int( 'type', -1 );
 +:
 +?>
 +</code>
 +    * 儘量不要直接在程式碼內印出(print/echo) HTML, 除非這 HTML 很短或是在函式的回圈內((原則應該採用 Smarty 的方式顯示 HTML))
 +    * 不要使用 EOF 這有意義的字當結構標籤(aaa EOF bbb : 以 EOF 來當判別區別資料項)((對 EOF Construct 如果有比較好的翻譯或解釋請在告訴我..))
 +
 +
 +
 +
 +===== - 其他 =====
 +
 +    * 不要使用 ?: 當結構標籤, 這樣會造成混淆以及有可能是造成問題的潛在原因.
 +    * 避免使用 magic numbers. 所使用的 magic numbers 應該只有 1 和 0 而且是出現在很容易理解的地方.
 +
 +
 +
 +===== - 頁面標準 =====
 +
 +    * 版權說明應該是要放在程式碼最上方(這部分應該包含版本相關資訊)
 +<code php>
 +<?php
 +# 專案代號 - 專案名稱
 +# Copyright (C) 2002 - 2005  專案負責人 - 聯絡 E-Mail
 +# This program is distributed under the terms and conditions of the GPL <- 採用的版權方式
 +# See the README and LICENSE files for details
 +
 +# --------------------------------------------------------
 +# $Id: 檔案名稱,v 版本編號 異動日期 時間 異動者 Exp $
 +# --------------------------------------------------------
 +?>
 +
 +例如 :
 +
 +<?php
 +# viaDocExg - 公文電子交換系統
 +# Copyright (C) 2006 - 2007  Jonathan Tsai - [email protected]
 +# This program is distributed under the terms and conditions of the GPL
 +# See the README and LICENSE files for details
 +
 +# --------------------------------------------------------
 +# $Id: main.php,v 1.00 2007/1/02 上午 12:07 jonathan Exp $
 +# --------------------------------------------------------
 +?>
 +
 +</code>
 +    * print_ 這樣的函式應該是出現在最底下((原則上如果是 HTML, 應該是呼叫 smarty 的 display() ))
 +
 +
 +===== - 大括號和小括號 =====
 +
 +    * 函式右邊應該緊接著小括號, 例如. function() , 而不是 function () <- 函式與括號間多空了一格
 +    * 系統保留字(if, while, for)右邊應該先空一格再接著小括號, 例如. for (...)
 +    * 陣列括號與裡面的索引變數間不應該出現空格, 例如. $arr['index'] 而不是 $arr[ 'index' ] <- 括號裡面多了空格
 +    * 使用大括號的格式請參考以下實例說明, 請採用非對齊位置格式.
 +<code php>
 +      for (...) {
 +          blah
 +      }
 +
 +      或
 +
 +      if (...) {
 +          blah
 +      }
 +</code>
 +    * if ... else 應該要如以下的格式:
 +<code php>
 +      if (...) {
 +          blah1
 +      } else {
 +          blah2
 +      }
 +</code>
 +
 +
 +===== - 邏輯運算與判別式 =====
 +
 +    * NOT 這運算元(!)應該要緊接在變數前面, 不要空格, 例如. !$value
 +    * 要擅用括號的好處, 特別是在複雜的邏輯運算式中, 例如. if ( ( null == $val ) && ( null == $val2 ) )
 +
 +
 +===== - 字串 =====
 +
 +    * 字串相連之間要留空白字元, 例如. 'str ' . $value . ' str2';
 +    * 如果沒有特殊的狀況, 應該使用 ' (單引號)來取代 " (雙引號)
 +
 +
 +===== - 註解 =====
 +
 +    * 以 # 這個符號來當註解開頭, 而不是 <code>//</code>
 +    * 使用 /* */ 來標註整個註解區塊. 一般而言, 這只用在開發過程.
 +    * 使用 @@@ 來標示簡短的訊息, 這樣可以留下讓程式碼中可以改善想法, 所以應該在 @@@ 後面先接著自己的姓名或代號, 然後才是訊息內容. 範例如下:
 +
 +<code php>
 +:
 +    $t_setting_arr['relationship_bug'] = 0;
 +    $t_custom_fields = custom_field_get_ids(); # @@@ (thraxisp) This should really be the linked ids, but we don't know the project
 +    $t_custom_fields_data = array();
 +:
 +</code>
 +
 +
 +===== - 程式碼編輯工具應該有的特點 =====
 +
 +    * 要能在多個檔案中同時對字串搜尋與取代功能
 +    * 能直接跳到指定的行號處
 +    * 對程式語法能夠區分出來(函式, 變數, 保留字 能夠以不同顏色標示)
 +    * 能夠依據 TAB 來對齊
 +    * 推薦使用 [[http://notepad-plus.sourceforge.net/tw/site.htm|Notepad++]]((Notepad++ 是 OpenSource 免費好用編輯軟體, 作者是侯今吾先生)) 或 [[http://www.editplus.com/|EditPlus]]((EditPlus 2.11 我覺得就夠用了, 千萬不要使用中文化等非原始公司提供的版本, 否則存成 UTF-8 可能會和 UltraEdit 一樣出現怪異的問題)) 這樣的編輯工具
 +    * 如果沒有特殊狀況, 應該要將程式碼存成 UTF-8 格式
 +
 +
 +{{tag>程式設計 php 密技}}