軟件開發(fā)編碼規(guī)范參考模板

1、軟件開發(fā)編碼規(guī)范(C#)1 / 14目 錄1引言41.1編寫目的41.2背景41.3定義41.4參考資料42基本要求42.1程序結(jié)構(gòu)要求42.2可讀性要求42.3結(jié)構(gòu)化要求52.4正確性與容錯性要求52.5可重用性要求63用戶界面設(shè)計原則64源程序書寫規(guī)范64.1通用源代碼格式規(guī)則64.1.1縮進(jìn)64.1.2邊距74.1.3“”的使用74.1.4注釋74.2語句格式與語句書寫規(guī)范74.2.1括號84.2.2保留字和關(guān)鍵字84.2.3函數(shù)84.2.4變量84.2.5語句85命名規(guī)范105.1函數(shù)命名105.2形參105.3常量和變量105.3.1常量和宏定義105.3.2變量105.4函數(shù)使用說

2、明、接口命名、NameSpace命名115.5控件的命名125.6類型125.6.1一般類型125.6.2構(gòu)造類型135.6.3類類型135.7文件和文件夾135.7.1文件夾的命名規(guī)則135.7.2文件命名146源程序文檔注釋規(guī)范146.1注釋文檔的一般規(guī)范141 引言1.1 編寫目的本規(guī)范旨在用規(guī)范文件的形式，對全公司使用C#進(jìn)行的編程過程，進(jìn)行有效的規(guī)范管理，使得最終的軟件產(chǎn)品具有良好的風(fēng)格和統(tǒng)一的結(jié)構(gòu)，且使代碼可讀性強(qiáng)、易維護(hù)。 本規(guī)范預(yù)期讀者是全公司所有參與編程的軟件開發(fā)人員以及其他相關(guān)人員。本標(biāo)準(zhǔn)適用于Visual C# ,其余語言作參考。1.2 背景公司在上一個項(xiàng)目中由于代碼編寫

3、風(fēng)格不統(tǒng)一，可讀性較差、較難維護(hù)，使得工作效率有所降低。1.3 定義 無1.4 參考資料Pascal Standards FAQ (E)JavaDoc （E）Doc-O-matic Document (E)Artemis Alliance Delphi Coding Standards (E)C#基本書寫規(guī)范C#編碼規(guī)范綱要2 基本要求2.1 程序結(jié)構(gòu)要求程序結(jié)構(gòu)清晰，簡單易懂，單個函數(shù)的程序行數(shù)一般不得超過100行,個別特殊函數(shù)除外。代碼中打算干什么，要簡單，直接了當(dāng)，代碼精簡，避免垃圾程序。應(yīng)盡量使用.NET庫函數(shù)和公共函數(shù)(無特殊情況不要使用外部方法調(diào)用windows的核心動態(tài)鏈接庫)。

4、一般情況下，不得使用全局變量，盡量使用局部變量。2.2 可讀性要求可讀性第一，效率第二。（這僅對代碼本身而言）。保持注釋與代碼完全一致。每個源程序文件，都必須有文件頭說明，說明規(guī)格見“源程序文檔注釋規(guī)范”一節(jié)。每個函數(shù)，都必須有函數(shù)頭說明，說明規(guī)格見“源程序文檔注釋規(guī)范”一節(jié)。主要變量（結(jié)構(gòu)、聯(lián)合、類或?qū)ο螅┒x或引用時，注釋必須能反映其物理含義。處理過程的每個階段都必須有相關(guān)注釋說明。在典型算法前都必須有注釋, 同時算法在滿足要求的情況下應(yīng)盡可能簡單。利用縮進(jìn)來顯示程序的邏輯結(jié)構(gòu)，縮進(jìn)量一致以Tab鍵為單位，定義Tab為 4個字節(jié)。循環(huán)、分支層次不要超過五層。注釋可以與語句在同一行，也可以在

5、上行?？招泻涂瞻鬃址彩且环N特殊注釋。一目了然的語句不加注釋。注釋的作用范圍可以為：定義、引用、條件分支以及一段代碼。注釋行數(shù)（不包括文件頭和函數(shù)頭說明部份）應(yīng)占總行數(shù)的 1/5 到 1/3。常量定義（const）有相應(yīng)說明。2.3 結(jié)構(gòu)化要求禁止出現(xiàn)兩條等價的支路。禁止GOTO語句。用 IF 語句來強(qiáng)調(diào)只執(zhí)行兩組語句中的一組。禁止 ELSE GOTO 和 ELSE RETURN。用 CASE 實(shí)現(xiàn)多路分支。避免從循環(huán)引出多個出口。函數(shù)只有一個出口。不使用復(fù)雜的條件賦值語句。避免不必要的分支。不要輕易用條件分支去替換邏輯表達(dá)式。2.4 正確性與容錯性要求程序首先是正確，其次是優(yōu)美。無法證明你的

6、程序沒有錯誤，因此在編寫完一段程序后，應(yīng)先回頭檢查。改一個錯誤時可能產(chǎn)生新的錯誤，因此在修改前首先考慮對其它程序的影響。所有變量在調(diào)用前必須被初始化。對所有的用戶輸入，必須進(jìn)行合法性檢查。不要比較浮點(diǎn)數(shù)的相等，如： 10.0 * 0.1 = 1.0 ， 不可靠。程序與環(huán)境或狀態(tài)發(fā)生關(guān)系時，必須主動去處理發(fā)生的意外事件，如文件能否邏輯鎖定、打印機(jī)是否聯(lián)機(jī)等,對于明確的錯誤,要有明確的容錯代碼提示用戶。單元測試也是編程的一部份，提交聯(lián)調(diào)測試的程序必須通過單元測試。盡量使用規(guī)范的容錯語句。 例如:trycatchfinally2.5 可重用性要求重復(fù)使用的完成相對獨(dú)立功能的算法或代碼應(yīng)抽象為服務(wù)或類

7、。服務(wù)或類應(yīng)考慮面向?qū)ο?OO)思想，減少外界聯(lián)系，考慮獨(dú)立性或封裝性。3 用戶界面設(shè)計原則除標(biāo)題部分外，所有顯示給用戶的字體（如BUTTON和LABEL等）使用標(biāo)準(zhǔn)字體：宋體、九號、黑色；標(biāo)題部分可用醒目的字體，如：宋體、小二號、紅色。采用Windows缺省的風(fēng)格。窗體盡量從已有的父窗體繼承。方便用戶對信息的輸入、修改和閱讀。驗(yàn)證用戶輸入的有效性和合理性。具有清晰明確的用戶提示信息。使用Tab鍵在輸入項(xiàng)之間移動輸入焦點(diǎn)（可選）。標(biāo)準(zhǔn)按鈕大小必須相同，使用的圖像和標(biāo)題必須與界面風(fēng)格規(guī)范一致，如果出現(xiàn)該規(guī)范中沒有的地方，須與項(xiàng)目負(fù)責(zé)人和美工協(xié)商。4 源程序書寫規(guī)范4.1 通用源代碼格式規(guī)則4.1

8、.1 縮進(jìn)縮進(jìn)就是每級間有一個Tab單位。不要在源代碼中放置制表符。這是因?yàn)?，制表符的寬度隨著不同的設(shè)置和代碼管理實(shí)用程序(打印、文檔及版本控制等)而不同。沿邏輯結(jié)構(gòu)行縮進(jìn)代碼。沒有縮進(jìn)，代碼將變得難以理解，如： if(expression ) /此處填寫你的代碼塊；/ if(expression ) /此處填寫你的代碼塊；/ else /此處填寫你的代碼塊；/縮進(jìn)代碼會產(chǎn)生出更容易閱讀的代碼，如： if(expression ) if(expression )/此處填寫你的代碼塊；/else/此處填寫你的代碼塊；/4.1.2 邊距 邊距設(shè)置為80個字符。源代碼一般不會因?qū)懸粋€單詞而

9、超過邊距，但本規(guī)則比較靈活。只要可能，長度超過一行的語句應(yīng)當(dāng)用分行符換行。換行后，應(yīng)縮進(jìn)兩個字符。 4.1.3 “”的使用“”或“”必須單獨(dú)占一行。例如: 錯誤形式：for（i:=0；i<10；i+） / 錯, “” 與f o r 在同一行 正確形式：for（i:=0；i<10；i+） / 對, “”在另外一行中4.1.4 注釋通常使用“/*.*/”類型的塊注釋和“/”類型的行注釋。4.2 語句格式與語句書寫規(guī)范4.2.1 括號 在左括號與下一字符之間沒有空格。同樣，右括號與前一字符也沒有空格。下面的例子演示了正確與不正確的空格。CallProc( aParameter

10、)； / 錯!CallProc(aParameter)； / 正確!4.2.2 保留字和關(guān)鍵字在用戶的各種命名中不能單獨(dú)使用保留字或關(guān)鍵字來進(jìn)行命名。4.2.3 函數(shù) 格式函數(shù)名要能體現(xiàn)出該函數(shù)要實(shí)現(xiàn)的功能，應(yīng)當(dāng)以大寫字母開始，且大小寫交錯以增加可讀性(每個單詞的首字母大寫)。下面是一個不正確的寫法：pubilc void thisisapoorlyformattedroutinename()下面是正確的寫法：pubilc void ThisIsMuchMoreReadableRoutineName() 形參1）參數(shù)順序  形參的順序主要要考慮寄存器調(diào)用規(guī)

11、則。最常用的參數(shù)應(yīng)當(dāng)作為第一個參數(shù)，按使用頻率依次從左到右排。輸入?yún)?shù)位于輸出參數(shù)之前。范圍大的參數(shù)應(yīng)當(dāng)放在范圍小的參數(shù)之前。例如：SomeProc(aPlanet, aContinent, aCountry, aState, aCity).  有些則例外。例如，在事件處理過程中，Object 類型的Sender 參數(shù)往往是第一個要傳遞的參數(shù)。2）常量參數(shù)  任何值類型參數(shù)，只要不加REF標(biāo)志，都是常量參數(shù)；任何引用類型參數(shù)，都不是常量參數(shù)，不管加不加標(biāo)志。4.2.4 變量 局部變量  局部變量用于過程內(nèi)部，如果需要的話，應(yīng)當(dāng)在過程的入口處立即初始化

12、變量。 全局變量  一般不鼓勵使用全局變量。不過，有時候需要用到。即使如此，也應(yīng)當(dāng)把全局變量限制在需要的環(huán)境中。例如，一個全局變量可能只在單元的實(shí)現(xiàn)部分是全局的。  全局?jǐn)?shù)據(jù)如果將由許多單元使用，就應(yīng)移動到一個公用單元里被所有對象使用。全局?jǐn)?shù)據(jù)可在聲明時直接初始化為一個值。4.2.5 語句 If 語句  在if/else語句中， if子句的條件應(yīng)該直接且易于理解。為了避免出現(xiàn)許多if語句，可以使用switch語句代替。如果多于5級，不要使用if語句。請改用更清楚的方法。  如果在if語句中有多個條件要測試，應(yīng)按照計算的復(fù)雜程度

13、從右向左排。這樣，可以使代碼充分利用編譯器的短路估算邏輯。例如，如果Condition1比Condition2快，Condition2比Condition3快，則if語句一般應(yīng)這樣構(gòu)造：if （Condition1 && Condition2 && Condition3）   如果Condition3為False的機(jī)會很大，利用短路估算邏輯，我們也可以將Condition3放在最前面：if （Condition3 && Condition1 && Condition2） 有if出現(xiàn),就必須有對應(yīng)的else出現(xiàn)。if語句的

14、三種形式:1) 形式一(不需要else) if (Condition) Process；/else/ No Else Needed/2) 形式二(需要else,但是else里面不需要處理) if (Condition) Process；else/No Need Process3) 形式三(if里面不需要處理) if (Condition)/ No Need ProcesselseProcess； switch 語句1）概述  switch語句中每種情況的常量應(yīng)當(dāng)按數(shù)字或字母的順序排列。每種情況的動作語句應(yīng)當(dāng)簡短且通常不超過4 - 5 行代碼。如果動作太復(fù)雜，應(yīng)將代碼單獨(dú)

15、放在一個函數(shù)中。switch語句的else子句只用于默認(rèn)情況或錯誤檢測。2）格式  switch語句遵循一般的縮進(jìn)和命名規(guī)則。 while 語句  所有對while循環(huán)進(jìn)行初始化的代碼應(yīng)當(dāng)位于while入口前，且不要被無關(guān)的語句隔開。任何業(yè)務(wù)的輔助工作都應(yīng)在循環(huán)后立即進(jìn)行。 for 語句如果循環(huán)次數(shù)是確定的，應(yīng)當(dāng)用for語句代替while語句。5 命名規(guī)范5.1 函數(shù)命名  函數(shù)名應(yīng)當(dāng)有意義。進(jìn)行一個動作的函數(shù)最好在名稱前加上表示動作的動詞為前綴。例如：public void FormatHardDrive()  設(shè)置輸入?yún)?shù)

16、值的函數(shù)名應(yīng)當(dāng)以Set 為其前綴，例如：public void SetUserName()  獲取數(shù)值的函數(shù)名應(yīng)當(dāng)以Get 為其前綴，例如：public string GetUserName()函數(shù)名稱第一個字母必須使用大寫字母,要求用大小寫字母組合規(guī)范函數(shù)命名,必要時可用下劃線間隔,示例如下：public void PrintTrackData()public void ShowChar(int aIndex, char aszMyChar)5.2 形參  所有形參的名稱都應(yīng)當(dāng)表達(dá)出它的用途。如果合適的話，形參的名稱最好以字母a 為前綴，例如：public void So

17、meProc(string aUserName, integer aUserAge)當(dāng)參數(shù)名與類的特性或字段同名時，前綴a 就有必要了。5.3 常量和變量5.3.1 常量和宏定義  常量和宏定義必須具有一定的實(shí)際意義；常量和宏定義必須全部以大寫字母,中間可根據(jù)意義的連續(xù)性用下劃線連接,每一條定義的右側(cè)必須有一簡單的注釋,說明其作用。資源名字定義格式:菜單:IDM_XX或者CM_XX位圖:IDB_XX對話框:IDD_XX字符串:IDS_XXDLGINIT:DIALOG_XXICON:IDR_XX5.3.2 變量  變量命名必須具有一定的實(shí)際意義,形式為xAbcFgh,x由變量

18、類型確定,Abc、Fgh表示連續(xù)意義字符串,如果連續(xù)意義字符串僅兩個,可都大寫，如OK 。常用的變量舉例如下:縮寫類型舉例dtDateTimedtTextszcharszTextsbsbytesbTextbtbytebtTextnintnTextuiuintuiTextllonglTextululongulTextffloatfTextddoubledTextbboolbTextdedecimaldeTextstrstringstrText 以下面字母或符號作為前綴，分別具有如下意義：x,y 坐標(biāo)att 表屬性c 類對象 cMain（對象實(shí)例）m_ 類成員變量 m_nVal, m_bFlags

19、_ 類靜態(tài)成員變量 s_nVal,s_bFlag 局部變量局部變量遵循其他變量的命名規(guī)則。通常以“n”作為前綴。局部變量中可采用如下幾個通用變量：nTemp，nResult，I，J（一般用于循環(huán)變量）。 全局變量  全局變量一般以字母“g”打頭，并遵循其他變量的命名規(guī)則。5.4 函數(shù)使用說明、接口命名、NameSpace命名函數(shù)使用說明包括外來函數(shù)及內(nèi)部函數(shù)的使用說明，外部引用函數(shù)必須在右側(cè)注明函數(shù)來源： 模塊名及文件名, 如是內(nèi)部函數(shù)，只要注釋“l(fā)ocal module”即可。例如：strName=GetUserName(strUserId)；/ loc

20、al modulestrName= GetUserName(strUserId)；/ Module Name:UserManage / File Name: fm UserManage 事件函數(shù)的使用說明: public void EventHandler(object sd,Event e) /Event 表示事件響應(yīng)的函數(shù)。接口命名： 接口的命名一般都以“I”作為首字母,為了和類區(qū)分,例如: interface IComnunication 命名空間：命名空間命名規(guī)則從原則上和函數(shù)命名相同。通常格式如下：NameSpace命名：N+ 部署位置 + 項(xiàng)目名稱 + namespace名稱 其他

21、： Application命名 P + 部署位置 + 項(xiàng)目名稱5.5 控件的命名C#控件規(guī)則為了和.net類庫統(tǒng)一,分WindowsForm程序和Web程序。下面就這兩部分分別描述。1）WindowsForm程序 （用小寫前綴表示類別） fm 窗口cmd 按鈕cob combo，下拉式列表框txt 文本輸入框lab labal，標(biāo)簽img image，圖象pic picturegrd Grid，網(wǎng)格scr 滾動條lst 列表框frm fram2）Web程序 （用大寫前綴表示類別） Fm 窗口Cmd 按鈕Cob combo，下拉式列表框Txt 文本輸入框Lab labal，標(biāo)簽Img image

22、，圖象Pic pictureGrd Grid，網(wǎng)格Scr 滾動條Lst 列表框Frm fram5.6 類型5.6.1 一般類型 枚舉型  枚舉類型名必須代表枚舉的用途。枚舉類型的標(biāo)識符列表的前綴應(yīng)包含2 - 3 個小寫字符，來彼此關(guān)聯(lián)。例如：enum SongType=stRock, stClassical, stCountry, stAlternative, stHeavyMetal, stRB；5.6.2 構(gòu)造類型 數(shù)組類型  數(shù)組類型名應(yīng)表達(dá)出該數(shù)組的用途。例如：string weekDays = new string7；字符串型數(shù)組wee

23、kDays包括7個元素。 結(jié)構(gòu)體類型 結(jié)構(gòu)體類型命名必須全部用大寫字母,原則上前面以下劃線開始；結(jié)構(gòu)體變量命名必須用大小寫字母組合，第一個字母必須使用大寫字母,必要時可用下劃線間隔。對于私有數(shù)據(jù)區(qū)，必須注明其所屬的進(jìn)程。全局?jǐn)?shù)據(jù)定義只需注意其用途。示例如下：public struct DBS_DATABASEchar szProductName20； char szAuthor20； char szReleaseDate16； char szVersion10；  unsigned long MaxTables； unsigned long UsedTables； DBS_DATABASE GdataBase；5.6.3 類類型 類命名與格式  類的名稱應(yīng)當(dāng)表達(dá)出類的用途。一般的類名前要加字母“C”，如果是接口類那么類名前要加“I”，錯誤異常類的類名前要加“E”，而類引用類型（Class-reference type）則要在類名后加“Class”，抽象類一般是在類名前還要加“Abstract”。 屬性命名規(guī)則屬性的命名遵循與變量相同的規(guī)則，只不過要加前綴“f”，表示這是屬性。 方法命名規(guī)則  方法的命名遵循與過程和函數(shù)相同的規(guī)則。5.7 文件和文件夾5.7.1