C編碼規(guī)范中文

1、C# 編碼規(guī)范When this document is released, it is to be followed and adhered to. If you have suggestions for improving this document, please e-mail your ideas to the author listed on the cover page. When released, a Change Control Board (CCB) would have reviewed this document and approved electronically

2、via a Document Change Order (DCO).目錄1目標(biāo)42概述43總體要求43.1程序結(jié)構(gòu)化43.2代碼可讀性43.3代碼結(jié)構(gòu)化53.4正確性與容錯(cuò)性53.5可重用性54編碼規(guī)范64.1文件結(jié)構(gòu)6C# 文件6目錄結(jié)構(gòu)64.2縮進(jìn)6換行6空格74.3注釋7模塊注釋7單行注釋8類注釋8方法注釋84.4聲明9單行聲明變量數(shù)9初始化9類和接口聲明94.5功能語(yǔ)句10簡(jiǎn)單邏輯10返回語(yǔ)句10if-else語(yǔ)句10For / Foreach 語(yǔ)句11While/do-while 語(yǔ)句11Switch 語(yǔ)句11Try-catch 語(yǔ)句124.6空白12空白行12參數(shù)條件之間的空白13

3、表格式的樣式134.7命名規(guī)范14大寫14Pascal 風(fēng)格14駝峰規(guī)則14大寫風(fēng)格14命名方法14類命名15接口命名15枚舉命名15常量命名15參數(shù)命名15變量命名15方法命名15屬性命名16事件命名16大寫風(fēng)格164.8開發(fā)習(xí)慣16可見性16不要硬編碼數(shù)字174.9代碼示例17作用域（“”）示例175參考186附錄186.1XML注釋標(biāo)記的使用187修改歷史221 目標(biāo)為新宇DotNet組的C#程序員制定一個(gè)統(tǒng)一的編碼規(guī)范，最大限度減少不同程序員開發(fā)的代碼間的差異。2 概述 為了使應(yīng)用程序的結(jié)構(gòu)和編碼風(fēng)格標(biāo)準(zhǔn)化，便于閱讀和理解編碼，以提高開發(fā)效率和產(chǎn)品的標(biāo)準(zhǔn)化，制訂一套開發(fā)規(guī)范和標(biāo)準(zhǔn)勢(shì)在必

4、行。此外，好的編碼約定可使源代碼嚴(yán)謹(jǐn)、可讀性強(qiáng)且意義清楚，與其它語(yǔ)言約定相一致，并且盡可能的直觀。希望開發(fā)人員嚴(yán)格遵守此套開發(fā)規(guī)范和標(biāo)準(zhǔn)，并落實(shí)到自己的程序中。本規(guī)范主要針對(duì)C#程序員，但是其中許多規(guī)則同時(shí)適用于其他語(yǔ)言的程序員。3 總體要求3.1 程序結(jié)構(gòu)化· 程序結(jié)構(gòu)清晰，函數(shù)功能簡(jiǎn)單易懂（單個(gè)函數(shù)的代碼行數(shù)不超過100行）3.2 代碼可讀性· 保持注釋與代碼完全一致· 每個(gè)源程序文件，都有文件頭說明，詳細(xì)見下節(jié)· 每個(gè)函數(shù)，都有函數(shù)頭說明，詳細(xì)見下節(jié)· 主要變量（結(jié)構(gòu)、聯(lián)合、類或?qū)ο螅┒x或引用時(shí)，注釋能反映其含義· 處理過程的

5、每個(gè)階段都有相關(guān)注釋說明· 在典型算法前都有注釋, 同時(shí)算法在滿足要求的情況下盡可能簡(jiǎn)單· 利用縮進(jìn)來顯示程序的邏輯結(jié)構(gòu)，縮進(jìn)量一致并以Tab鍵為單位，定義Tab為 4個(gè)字節(jié)· 循環(huán)、分支層次一般不應(yīng)超過五層· 代碼簡(jiǎn)單的分支應(yīng)該寫在前面· 不允許同行出現(xiàn)兩個(gè)語(yǔ)句· 空行和空白字符也是一種特殊注釋· 一目了然的語(yǔ)句不加注釋· 注釋的作用范圍可以為：定義、引用、條件分支以及一段代碼· 常量定義（DEFINE）有相應(yīng)說明3.3 代碼結(jié)構(gòu)化· 禁止GOTO語(yǔ)句· 用 CASE 實(shí)現(xiàn)多路分支&

6、#183; 避免不必要的分支· 用 IF 語(yǔ)句來強(qiáng)調(diào)只執(zhí)行兩組語(yǔ)句中的一組。盡量不使用 ELSE RETURN · 盡量避免從循環(huán)引出多個(gè)出口3.4 正確性與容錯(cuò)性· 所有變量在調(diào)用前必須被初始化· 不要比較浮點(diǎn)數(shù)的相等，如： 10.0 * 0.1 = 1.0 ， 不可靠· 訪問外部資源(數(shù)據(jù)庫(kù)，外部文件)時(shí)使用規(guī)范的容錯(cuò)語(yǔ)句例如:trycatchfinally4 編碼規(guī)范4.1 文件結(jié)構(gòu)4.1.1 C# 文件盡量不要讓你的類或者文件太長(zhǎng),一般不應(yīng)超過2000行代碼。請(qǐng)按照功能劃分你的代碼，使結(jié)構(gòu)保持清晰。一般情況下，一個(gè)文件應(yīng)當(dāng)只有一個(gè)類，并

7、且文件名應(yīng)該與類名保持一致。 4.1.2 目錄結(jié)構(gòu)應(yīng)該為每個(gè)名稱空間(namespace)建立一個(gè)目錄(例如，我們可以為名稱空間建立這樣的目錄：MyProject/TestSuite/TestTier)。這樣做可以讓你很快定位到指定名稱空間下的類文件。 4.2 縮進(jìn)4.2.1 換行如果表達(dá)式太長(zhǎng)而一行無法寫下時(shí)，請(qǐng)按照下列規(guī)范進(jìn)行換行： l 可以在逗號(hào)后面進(jìn)行換行 l 可以在操作符號(hào)后進(jìn)行換行 l 盡量選擇在較高層處進(jìn)行換行 l 換行后的新行應(yīng)當(dāng)與前一行中同級(jí)別的運(yùn)算符對(duì)齊 例子：方法調(diào)用換行： longMethodCall(expr1, expr2,   

8、60;           expr3, expr4, expr5); 算術(shù)表達(dá)式換行：規(guī)范的:var = a * b / (c - g + f) +      4 * z;不規(guī)范的:var = a * b / (c - g +      f) + 4 * z; 上面第一個(gè)表達(dá)式的換行方式是符合規(guī)范的，它換行在括號(hào)外面（較高層）。另外請(qǐng)注意，換行后的新行應(yīng)使用tab和

9、空格保持與前一行的同級(jí)運(yùn)算符對(duì)齊，例如: > var = a * b / (c - g + f) +> .4 * z;'>'表示Tab符， '.'表示空格。你可以設(shè)置你的編輯環(huán)境，使Tab和空格在編輯時(shí)是可見的，這是一個(gè)不錯(cuò)的習(xí)慣。 4.2.2 空格我們選擇Tab縮進(jìn)作為縮進(jìn)時(shí)采用的標(biāo)準(zhǔn)。 請(qǐng)不要使用空格代替Tab鍵!4.3 注釋4.3.1 模塊注釋在一個(gè)程序模塊的開始，應(yīng)用注釋說明模塊的名字、功能、開發(fā)者和日期和版本變更歷史，如下所示：/* * Copyright(c) Suzsoft DotNet Group * Description :

10、 Tenant access class * CreateDate : 2006-06-02 05:03:46 * Creater : Johnson Cao * LastChangeDate: * LastChanger : * Version Info : 1.0 * */ 4.3.2 單行注釋程序員應(yīng)當(dāng)在算法比較復(fù)雜的表達(dá)式前、特殊含義的變量前或者在一整段功能代碼開始之前添加適當(dāng)?shù)淖⑨尅Ｎ覀円筮@樣的單行 注釋采用”/”符號(hào)，例如：/ Calculate subTotalDecimal subTotal = 0;4.3.3 類注釋在定義一個(gè)類之前，應(yīng)用“/”注釋說明類的功能、使用方法和特

11、殊的屬性，如下所示：/ <summary>/ This class./ <remarks>/ Please note / </remarks>/ </summary>詳細(xì)的xml注釋標(biāo)記的使用請(qǐng)參見附錄。 4.3.4 方法注釋在定義類成員方法前，應(yīng)說明該過程/函數(shù)的名字、功能、輸入/輸出和版本變更歷史，如下所示：/ <summary>/ This method ./ <param name="param1">this is a param of the method SomeMethod.</pa

12、ram>/ <retvalue>a return object</retvalue>/ </summary>/-/ Change History:/ DateWho Changes Made/ 2000-5-1Author1Initial creation/ 2000-5-15Author2Add some code/-public object SomeMethod(object param1)4.4 聲明4.4.1 單行聲明變量數(shù)我們推薦每行只聲明一個(gè)變量，因?yàn)檫@樣你可以在聲明后面寫上該變量的注釋，例如：int level; / indentati

13、on levelint size; / size of table請(qǐng)不要在同一行聲明不同含義的變量，比如： int a, b; /What is 'a'? What does 'b' stand for?上面的例子同樣可以說明了沒有意義的變量名稱會(huì)讓人很難理解，因此，在定義變量的時(shí)候，我們一定要給它們一個(gè)有含義的名字。 4.4.2 初始化最好在一定義后就初始化變量，例如：string name = strObject.Name;or int val = time.Hours;注意：如果你想要初始化對(duì)話框變量，建議使用using 聲明方式例如：using (Ope

14、nFileDialog openFileDialog = new OpenFileDialog() .4.4.3 類和接口聲明在聲明類和接口的時(shí)候應(yīng)當(dāng)遵照下列規(guī)范： l 方法名稱和放置參數(shù)的括號(hào)”(”之間不應(yīng)該有空格 l 類名聲明之后應(yīng)另起一行寫作用域開始符” l 作用域結(jié)束符”應(yīng)當(dāng)單獨(dú)占一行，并與對(duì)應(yīng)的開始符”處在同一縮進(jìn)位置上 示例： Class MySample : MyClass, IMyInterfaceint myInt;public MySample(int myInt)this.myInt = myInt ;void Inc()+myInt;void EmptyMethod()

15、4.5 功能語(yǔ)句4.5.1 簡(jiǎn)單邏輯每一行代碼應(yīng)當(dāng)只實(shí)現(xiàn)一個(gè)邏輯 4.5.2 if-else語(yǔ)句if-else應(yīng)該按照這種格式書寫：if(condition) DoSomething();. else DoSomethingOther();.4.5.3 For / Foreach 語(yǔ)句For循環(huán)語(yǔ)句格式：for(int i = 0; i < 5; +i) .或者，如果循環(huán)只有一個(gè)簡(jiǎn)單執(zhí)行語(yǔ)句的話：for (initialization; condition; update) ;foreach循環(huán)格式:foreach(int i in IntList) .注意：即使循環(huán)中只有一句執(zhí)行語(yǔ)句，

16、我們也要求使用” 4.5.4 While/do-while 語(yǔ)句While循環(huán)格式： while (condition) .對(duì)于空循環(huán)可以這樣寫：while (condition) ;do-while循環(huán)格式：do .while(condition);4.5.5 Switch 語(yǔ)句switch格式： switch (condition) case A:.break;case B:.break;default:.break;4.5.6 Try-catch 語(yǔ)句try-catch格式： try . catch (Exception) 或者：try . catch (Exception e) .或者

17、：try . catch (Exception e) . finally .4.6 空白4.6.1 空白行空白行有增強(qiáng)可讀性的作用。它們隔離了邏輯上相互獨(dú)立的模塊。l 在下列情況中我們還可以使用雙空白行： n 源文件中的兩個(gè)獨(dú)立的邏輯片斷之間n 類和接口之間（但一般情況下我們還是建議一個(gè)文件一個(gè)類或接口）l 下列情況中我們可以使用單空白行： n 方法之間 n 屬性之間n 方法內(nèi)局部變量第一出聲明前 n 方法內(nèi)相對(duì)獨(dú)立的邏輯之間 注意，盡量保持空白行和其他行具有同樣的縮進(jìn)，可以使今后插入代碼能夠保持相同的縮進(jìn)。 4.6.2 參數(shù)條件之間的空白通過這些空白，可以使代碼更容易被閱讀，例如：TestM

18、ethod(a, b, c); 而不應(yīng)該這樣： TestMethod(a,b,c)但是也不應(yīng)有過多的空格，比如：TestMethod( a, b, c );操作符和變量或數(shù)字之間應(yīng)該有空格：a = b; / don't use a=b;for (int i = 0; i < 10; +i) / don't use for (int i=0; i<10; +i)/ or/ for(int i=0;i<10;+i)4.6.3 表格式的樣式連續(xù)的多行付值語(yǔ)句可以這樣子寫：string strName = "Mr. Ed"int nValue =

19、5;Test aTest = Test.TestYou;利用空格對(duì)齊所有的“=”，使代碼塊看起來像表格一樣。 4.7 命名規(guī)范4.7.1 大寫 Pascal 風(fēng)格變量的首字母大寫，如：Name 駝峰規(guī)則除了首個(gè)單詞，每個(gè)單詞的首字母大寫，如：TestName 大寫風(fēng)格只在少于兩個(gè)字母的縮寫中使用大寫。三個(gè)以上字母的縮寫都應(yīng)該使用PASCAL風(fēng)格。4.7.2 命名方法通常我們采用匈牙利命名法來為變量命名。 匈牙利命名法通常采用變量類型的縮寫作為前綴，變量含義的全拼作為后綴的方法來命名變量。這種命名方法被廣泛的采用在windows程序開發(fā)中，它因由一匈牙利

20、程序員創(chuàng)立而得名。 注意：好的變量命名不是突出其類型，而是突出其含義。 對(duì)于UI控件，我們強(qiáng)制要求縮寫前綴，例如：System.Windows.Forms.Button btnCancel;System.Windows.Forms.TextBox txtName; 類命名l 使用名詞或名詞短語(yǔ)命名類。l 使用Pascal風(fēng)格.l 謹(jǐn)慎使用縮寫命名類。.l 不要使用任何類前綴（如C）. 接口命名l 使用名詞或名詞短語(yǔ)命名接口.(例如 IComponent 或 IEnumberable) l 使用Pascal風(fēng)格l 使用大寫的I作為首字母，表示為接口 枚

21、舉命名l 使用Pascal風(fēng)格l 不使用前綴 l 使用單數(shù)名詞命名 常量命名l 采用有意義的單詞命名 l 使用全部大寫字母拼寫 參數(shù)命名l 相對(duì)變量而言，參數(shù)更注重本身的含義作為命名 l 使用駝峰規(guī)則命名 變量命名l 作為循環(huán)中的運(yùn)算子的變量，更適合采用簡(jiǎn)單的命名，如i, j, k, l, m, n 方法命名l 采用動(dòng)詞命名，或者動(dòng)詞詞組 l 使用Pascal風(fēng)格 屬性命名l 使用名詞或名詞短語(yǔ)命名屬性 l 使用Pascal風(fēng)格 事件命名l 使用EventHandler作為事件句柄的后綴 l 使用兩個(gè)參數(shù)

22、：sender 和e l 使用Pascal風(fēng)格l 使用EventArgs 作為Event Argument類型名的后綴l 使用進(jìn)行時(shí)動(dòng)詞和過去式動(dòng)詞作為事件的名稱 0 大寫風(fēng)格TypeCaseNotesClass / StructPascal Casing InterfacePascal CasingStarts with IEnum valuesPascal Casing Enum typePascal Casing EventsPascal Casing Exception classPascal CasingEnd with Exce

23、ptionpublic FieldsPascal Casing MethodsPascal Casing NamespacePascal Casing PropertyPascal Casing Protected/private FieldsCamel Casing ParametersCamel Casing 4.8 開發(fā)習(xí)慣4.8.1 可見性請(qǐng)避免將類變量或一個(gè)實(shí)例聲明為公共類型的變量，而應(yīng)該將其聲明為私有變量。如果你確實(shí)需要公開一個(gè)類變量或者實(shí)例的話，可以使990用屬性(Property)來公開它。4.8.2 不要硬編碼數(shù)字也

24、就是說，在你的邏輯代碼中，不要采用數(shù)字直接參與計(jì)算，尤其是那些可能需要改變的數(shù)字。你應(yīng)該將它付值給一個(gè)常量，使用該常量參與計(jì)算。這樣做得好處是，如果這個(gè)數(shù)字改變的時(shí)候，你不必在代碼中將他找出并修改，而只需修改常量的值。public class MyMathpublic const double PI = 3.14159.4.9 代碼示例4.9.1 作用域（“”）示例namespace ShowMeTheBracketpublic enum Test TestMe,TestYoupublic class TestMeClassTest test;public Test Test get retu

25、rn test;set test = value;void DoSomething()if (test = Test.TestMe) /.stuff gets done else /.other stuff gets done作用域（"”）應(yīng)該在下列代碼后另起一行開始：l Namespace聲明后 l Class/ Interface / Struct 的聲明后 l Method聲明后 l 循環(huán)或者判斷(ifelse)后5 參考 6 附錄6.1 XML注釋標(biāo)記的使用6.1.1 Section 標(biāo)記Section 標(biāo)記用于定義不同的代碼文檔的區(qū)域。它們都是頂級(jí)標(biāo)記，Block 標(biāo)記、I

26、nline 標(biāo)記都應(yīng)包含在某個(gè) Section 標(biāo)記的內(nèi)部。（除非自定義了擴(kuò)展 XSLT 轉(zhuǎn)換，否則，在 Section 標(biāo)記外部的 Block 標(biāo)記或 Inline 標(biāo)記都被忽略。）標(biāo)記說明<event>NDoc 擴(kuò)充對(duì)某個(gè)成員可能引發(fā)的事件的說明。<example>“示例”，幫助類庫(kù)使用者理解類型/成員使用方法的示例代碼。<exception>對(duì)某個(gè)成員可以拋出的異常的說明。<exclude/>NDoc 擴(kuò)充指示 NDoc 文檔引擎將被標(biāo)記的類型/成員排除在代碼文檔之外。與文檔引擎的“可見性”配置不符的，以 exclude 優(yōu)先。<in

27、clude>將代碼文件外部的某 XML 文件中的一部分包含進(jìn)代碼文件來。<overloads>NDoc 擴(kuò)充為“重載列表”頁(yè)面準(zhǔn)備摘要、備注、示例等文檔內(nèi)容。只需在重載成員的第一個(gè)成員前面書寫此區(qū)域即可。<overloads> 標(biāo)記有兩種形式:· 簡(jiǎn)單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁(yè)面的摘要。沒有備注、示例等區(qū)域。 · 復(fù)雜的形式，在 overload 內(nèi)部，包含 summary, remarks, example 等標(biāo)記分別表示“重載列表”頁(yè)面的摘要、備注、示例等。 示例:/<overloads

28、>This method has two overloads.</overloads>/<summary>This overload just says hello.</summary>public void SayHello() . /<summary>This one says hello to someone.</summary>public void SayHello(string toSomeone) . <param>成員的參數(shù)說明。<permission>訪問某成員所必需的 .NET Fra

29、mework 安全性 CodeAccessPermission。<preliminary>NDoc 擴(kuò)充將某類型/成員標(biāo)記為“預(yù)發(fā)布”。內(nèi)部的文本被當(dāng)作警告文本用紅色顯示，可以包含 <para> 表示多行文本。如果缺少內(nèi)部文本，則顯示默認(rèn)的警告文本: “此文檔為預(yù)發(fā)布版本，在未來版本中有可能改變?！?。 如果需要把全部類型/成員都標(biāo)記為“預(yù)發(fā)布”，請(qǐng)使用文檔引擎的 Preliminary 配置項(xiàng)。<remarks>“備注”，對(duì) <summary> 的進(jìn)一步注解。<returns>“返回值”。<seealso>向頁(yè)面的“請(qǐng)參見

30、”區(qū)域添加一個(gè)鏈接。請(qǐng)不要將此標(biāo)記包含在 <remarks> 內(nèi)部，它是一個(gè)頂級(jí)標(biāo)記。兩種可選的語(yǔ)法:· <seealso href=" · <seealso cref="System.Data.DataSet">DataSet</seealso> <summary>“摘要”，對(duì)類型/成員的摘要說明。<threadsafety>NDoc 擴(kuò)充“線程安全”，說明類型在多線程環(huán)境中是否安全。NDoc 提供 static 和 instance 兩個(gè)布爾的屬性，可以自動(dòng)生成像 .NET Framework SDK 類庫(kù)文檔中那樣的標(biāo)準(zhǔn)文本。threadsafety 標(biāo)記內(nèi)部可以包含額外的文本，會(huì)被顯示到標(biāo)準(zhǔn)文本的下方，說明額外的信息。例如:/ <summary>The summary description for SafeClass.</summary>/ <threadsafety stati