第四章 編碼規(guī)范

1、ShopExShopEx編碼規(guī)范編碼規(guī)范編碼規(guī)范學(xué)習(xí)目標(biāo)v 在完成本章的學(xué)習(xí)后，您將能夠從以下幾個(gè)方面了解編碼規(guī)范：v 編輯器設(shè)定v 代碼布局v 注釋v 命名約定v 質(zhì)量保證v SQL語(yǔ)句 目錄大綱1.編輯器設(shè)定2.代碼布局3.注釋4.命名約定5.質(zhì)量保證6.SQL語(yǔ)句主要內(nèi)容v縮進(jìn)q1個(gè)Tab制表符為4個(gè)空格。PHP文件采用4個(gè)空格的縮進(jìn)，HTML文件以及HTML文件中嵌入的JavaScript代碼采用2個(gè)空格的縮進(jìn)；單獨(dú)的 JavaScript以及CSS文件采用4個(gè)空格的縮進(jìn)。v字符編碼q所有PHP、HTML文件均保存為UTF-8的字符編碼。1 編輯器設(shè)定 2 代碼布局 v 相對(duì)獨(dú)立的程序

2、塊之間、變量說(shuō)明之后必須加空行 q 示例：如下例子不符合規(guī)范if (!$valid_ni() . / program code $repssn_ind = $ssn_dataindex-repssn_index;$repssn_ni = $ssn_dataindex-ni; q 應(yīng)如下書寫:if (!valid_ni() . / program code $repssn_ind = $ssn_dataindex-repssn_index;$repssn_ni = $ssn_dataindex-ni;2 代碼布局v較長(zhǎng)的語(yǔ)句要分成多行書寫 v一行程序需小于80字符q較長(zhǎng)的語(yǔ)句要分成多行書寫，長(zhǎng)表

3、達(dá)式要在低優(yōu)先級(jí)操作符處劃分新行，操作符放在新行之首，劃分出的新行要進(jìn)行適當(dāng)?shù)目s進(jìn)，使排版整齊，語(yǔ)句可讀。2 代碼布局v斷行的例子q $perm_count_msg-len = NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * strlen( $len ); $act_task_table$frame_id * STAT_TASK_CHECK_NUMBER + $index-occupied = $stat_poiindex-occupied;v一行只寫一條語(yǔ)句不允許把多個(gè)短語(yǔ)句寫在一行中，即一行只寫一條語(yǔ)句。示例：如下例子不符合規(guī)范$rect

4、-length = 0; $rect-width = 0; 應(yīng)如下書寫:$rect-length = 0;$rect-width = 0;2 代碼布局v始終包含大括號(hào)這是因?yàn)閼杏诙嗲脙蓚€(gè)字符而給代碼清晰帶來(lái)問(wèn)題的又一個(gè)情形。 示例：如下例子不符合規(guī)范 if ($condition) do_stuff(); for ($i = 0; $i $size; $i+) do_stuff($i); 應(yīng)如下書寫 if (condition) do_stuff(); for ($i = 0; $i $size; $i+) do_stuff(); 2 代碼布局v大括號(hào)放在哪兒 程序塊的分界符（大括號(hào)和）應(yīng)各獨(dú)

5、占一行并且位于同一列，同時(shí)與引用它們的語(yǔ)句左對(duì)齊。在函數(shù)體的開始、類的定義、以及if、for、do、while、switch、case語(yǔ)句中的程序都要采用如上的縮進(jìn)方式。 示例：如下例子不符合規(guī)范for (.) . / program code應(yīng)如下書寫。for (.) . / program code2 代碼布局vswitch寫法示例：如下例子符合規(guī)范 switch ()case 1: .program break; case 2: .program break;2 代碼布局v符號(hào)之間使用空格采用這種松散方式編寫代碼的目的是使代碼更加清晰。由于留空格所產(chǎn)生的清晰性是相對(duì)的，所以，在已經(jīng)非常清

6、晰的語(yǔ)句中沒(méi)有必要再留空格，給操作符留空格時(shí)不要連續(xù)留兩個(gè)以上空格。 示例：如下例子不符合規(guī)范if ( ($i 8) ) . 應(yīng)如下書寫：if ( ($i 8) ) . 2 代碼布局v字符串連接符當(dāng)使用字符串連接符時(shí)必須在句點(diǎn)（.）兩側(cè)加上空格。示例：如下例子不符合規(guī)范$str = ;應(yīng)如下書寫：$str = ;2 代碼布局v空行的使用 誰(shuí)也不愿意看到擠在一堆的無(wú)序的代碼。我們?cè)趯懘a的時(shí)候總是會(huì)利用一些空行來(lái)增加代碼可讀性。合理的利用空格來(lái)區(qū)分代碼段會(huì)使代碼的邏輯思路更加明確。我們強(qiáng)行規(guī)定的空行有以下兩種情況：1、 之前必須有且只有1個(gè)空行3、兩個(gè)函數(shù)之間必須有1個(gè)空行。4、return、d

7、ie、exit之前如果有其他語(yǔ)句的情況下應(yīng)加上一個(gè)空行。在代碼中我們不允許在行尾有多余的空格。2 代碼布局v文件頭部模板文件頭部應(yīng)進(jìn)行注釋，注釋必須列出：版權(quán)說(shuō)明、版本號(hào)、生成日期、作者、內(nèi)容等。注：以ShopEx網(wǎng)上商店為例，其它項(xiàng)目可另行規(guī)定。/* * ShopEx網(wǎng)上商店 文件中文名稱= * 版權(quán)所有 (C) 2003-2009 上海商派網(wǎng)絡(luò)科技有限公司，并保留所有權(quán)利。 * 網(wǎng)站地址:http:/ * - * 您只能在不用于商業(yè)目的的前提下對(duì)程序代碼進(jìn)行修改和使用； * 不允許對(duì)程序代碼以任何形式任何目的的再發(fā)布。 * = */3 注釋v函數(shù)頭部注釋 每個(gè)函數(shù)之前應(yīng)當(dāng)有注釋，告訴一個(gè)程

8、序員使用這個(gè)函數(shù)所需要知道的事情。一個(gè)最小化的注釋應(yīng)包括：每個(gè)參數(shù)的意義，期望的輸入，函數(shù)的輸出。 /* * some_func * 函數(shù)的含義說(shuō)明 * * param mixed $arg1 參數(shù)一的說(shuō)明 * param mixed $arg2 參數(shù)二的說(shuō)明 * access public * return bool */3 注釋v注釋位置注釋應(yīng)與其描述的代碼相近，對(duì)代碼的注釋應(yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開$person_name=jack； / active statistic task number / active

9、statistic task numberDefine(MAX_ACT_TASK_NUMBER,1000) 3 注釋v連續(xù)case注釋對(duì)于switch語(yǔ)句下的case語(yǔ)句，如果因?yàn)樘厥馇闆r需要處理完一個(gè)case后進(jìn)入下一個(gè)case處理，必須在該case語(yǔ)句處理完、下一個(gè)case語(yǔ)句前加上明確的注釋。這樣比較清楚程序編寫者的意圖，有效防止無(wú)故遺漏break語(yǔ)句。示例：switch ($i) case CMD_INIT: echo i equals 0; break; case CMD_START: echo i equals 1;/ now jump into case CMD_A case C

10、MB_A: echo i equals 2; break;3 注釋v結(jié)構(gòu)體聲明代碼中代表結(jié)構(gòu)體的數(shù)組變量,要提前聲明。示例：function example_fun() $student = array(name = 小明, /名稱addr = 詳細(xì)地址, /地址sex = 男, /性別city = 上海 /城市 )3 注釋v注釋以中文為主 注釋應(yīng)考慮程序易讀及外觀排版的因素，使用的語(yǔ)言若是中、英兼有的，建議多使用中文，除非能用非常流利準(zhǔn)確的英文表達(dá)。3 注釋v禁止拼音命名法q代碼中禁止用拼音命名法。v變量命名q 變量名應(yīng)當(dāng)全部小寫，并且詞語(yǔ)之間以單個(gè)下劃線分隔。q 名稱應(yīng)當(dāng)是描述性的，并且簡(jiǎn)

11、明例如： $current_user 是正確的， 但是 $currentuser 和 $currentUser 就不正確。4 命名約定v函數(shù)命名 使用單詞間用單下劃線分隔的小寫名稱，允許動(dòng)賓詞組為執(zhí)行某操作的函數(shù)命名。示例： function input_record() function get_current_color() function is_boy()動(dòng)詞表：add / edit / remove begin / end create / destroy get / setincrement / decrement put / get lock / unlock open / cl

12、osestart / stop show / hide send / receive cut / paste 系詞表:is has4 命名約定v三元運(yùn)算符 q三元運(yùn)算符只應(yīng)該用來(lái)做簡(jiǎn)單的事情。它們只適合拿來(lái)做賦值用 示例：不應(yīng)該使用它們的地方 ($i $size) ? do_stuff($foo) : do_stuff($bar); 示例：使用它們的合適地方 $min = ($i $j) ? $i : $j;5 質(zhì)量保證v變量初始化 這個(gè)問(wèn)題最容易在檢查 HTML 表單傳遞了什么變量時(shí)出現(xiàn)。這些錯(cuò)誤可以通過(guò)使用內(nèi)嵌的 isset() 或者empty()函數(shù)檢查一個(gè)變量是否被設(shè)置來(lái)避免。 示例：

13、 老辦法if ($forum) . 新辦法：if (!empty($forum) .if （isset($forum)） 5 質(zhì)量保證v 引用字符串 在 PHP 中有兩種不同的方式引用字符串使用單引號(hào)或使用雙引號(hào)。主要區(qū)別是：解析器在雙引號(hào)括起的字符串中執(zhí)行變量替換，卻不在單引號(hào)括起的字符串中執(zhí)行示例：如下例子不符合規(guī)范$str = This is a really long string with no variables for the parser to find.; do_stuff($str); 應(yīng)如下書寫：$str = This is a really long string wi

14、th no variables for the parser to find.; do_stuff($str);5 質(zhì)量保證v 關(guān)聯(lián)數(shù)組的鍵名q在 PHP 中，使用一個(gè)不用引號(hào)括起來(lái)的字符串作為一個(gè)關(guān)聯(lián)數(shù)組的鍵名是可以運(yùn)行的。注意，這只是當(dāng)我們使用字符串時(shí)的情況，不是當(dāng)我們使用變量時(shí)的情況。示例：如下例子不符合規(guī)范 $foo = $assoc_arrayblah; 應(yīng)如下書寫：$foo = $assoc_arrayblah;5 質(zhì)量保證v 輸入變量的初始化q無(wú)論是函數(shù)的參數(shù)還是通過(guò)URL傳遞的變量，在調(diào)用之前均必須對(duì)其進(jìn)行預(yù)處理以及設(shè)定默認(rèn)值。 q字符串必須進(jìn)行trim及轉(zhuǎn)義的處理,并且如果變

15、量的值是在我們預(yù)計(jì)的范圍之內(nèi)，需要對(duì)變量的非法值做出相應(yīng)的處理；對(duì)于數(shù)字型的變量則需要進(jìn)行intval或者floatval的處理。5 質(zhì)量保證v require和includeq在程序中需要使用包含文件的時(shí)候我們要求使用require_once或者include_once，不允許使用require或者include。q對(duì)于程序必須包含的文件只能采用require_once，而對(duì)于某些有條件包含的文件在引用時(shí)只能使用include_once。5 質(zhì)量保證v 文件命名q 文件名應(yīng)當(dāng)全部小寫，并且詞語(yǔ)之間以單個(gè)下劃線分隔。 q 名稱應(yīng)當(dāng)是描述性的，并且簡(jiǎn)明例如： current_user.php 是

16、正確的， 但currentuser.php 和 currentUser.php 就不正確。5 質(zhì)量保證vSQL select 語(yǔ)句q 在已知需要查詢的字段的前提下，不允許使用如下的代碼：SELECT * FROM mytable 取而代之的寫法是將每一個(gè)字段名寫上去，請(qǐng)不要偷懶。 SELECT col1, col2, col3 FROM mytableq 在需要獲得已知記錄數(shù)量情況下，請(qǐng)使用 LIMIT offset, count 的方式，盡量不要使用無(wú) LIMIT 的 SELECT 語(yǔ)句。q 在需要或者滿足條件的記錄數(shù)量的情況下，請(qǐng)使用 SELECT count(*|col1) FROM 的方式，盡量不要使用 SELECT col1 FROM 的方式。6 SQL 語(yǔ)句 vSQL insert 語(yǔ)句q SQL INSERT 語(yǔ)句可以寫成兩種不同方式。或者你明確指明要插入的列，或者你已經(jīng)知道數(shù)據(jù)中各列的順序，不用詳細(xì)指定它們。我們希望使用前一種方法，也就是詳細(xì)說(shuō)明插入哪些列。這意味著應(yīng)用程序代碼不會(huì)依賴于數(shù)據(jù)庫(kù)中字段的順序，也不會(huì)因?yàn)槲覀冊(cè)黾恿硗獾淖侄味罎ⅰ? 這不是我們想要的