C#編碼規(guī)范(中文)

1、C# 編碼規(guī)范編碼規(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 electronic

2、ally via a Document Change Order (DCO). 目錄目錄 1目標(biāo)目標(biāo) .4 2概述概述 .4 3總體要求總體要求 .4 3.1程序結(jié)構(gòu)化.4 3.2代碼可讀性.4 3.3代碼結(jié)構(gòu)化.5 3.4正確性與容錯(cuò)性.5 3.5可重用性.5 4編碼規(guī)范編碼規(guī)范 .6 4.1文件結(jié)構(gòu).6 4.1.1C# 文件.6 4.1.2目錄結(jié)構(gòu).6 4.2縮進(jìn).6 4.2.1換行.6 4.2.2空格.7 4.3注釋.7 4.3.1模塊注釋.7 4.3.2單行注釋.8 4.3.3類注釋.8 4.3.4方法注釋.8 4.4聲明.9 4.4.1單行聲明變量數(shù).9 4.4.2初始化.9 4.4

3、.3類和接口聲明.9 4.5功能語句.10 4.5.1簡單邏輯.10 4.5.2返回語句.10 4.5.3if-else語句.10 4.5.4For / Foreach 語句.11 4.5.5While/do-while 語句.11 4.5.6Switch 語句.11 4.5.7Try-catch 語句.12 4.6空白.12 4.6.1空白行.12 4.6.2參數(shù)條件之間的空白.13 4.6.3表格式的樣式.13 4.7命名規(guī)范.14 4.7.1大寫.14 Pascal 風(fēng)格.14 駝峰規(guī)則.14 大寫風(fēng)格.14 4.7.2命名方法.14 4.7.2

4、.1類命名.15 接口命名.15 枚舉命名.15 常量命名.15 參數(shù)命名.15 變量命名.15 方法命名.15 屬性命名.16 事件命名.16 0大寫風(fēng)格.16 4.8開發(fā)習(xí)慣.16 4.8.1可見性.16 4.8.2不要硬編碼數(shù)字.17 4.9代碼示例.17 4.9.1作用域（“”）示例.17 5參考參考 .18 6附錄附錄 .18 6.1XML 注釋標(biāo)記的使用.18 7修改歷史修改歷史 .22 1目目標(biāo)標(biāo) 為新宇 DotNet 組的 C#程序員制定一個(gè)統(tǒng)一的編碼規(guī)

5、范，最大限度減少不同程序員開 發(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)勢在必行。此外，好的編碼約定可使源代碼嚴(yán)謹(jǐn)、 可讀性強(qiáng)且意義清楚，與其它語言約定相一致，并且盡可能的直觀。希望開發(fā)人員嚴(yán)格遵 守此套開發(fā)規(guī)范和標(biāo)準(zhǔn)，并落實(shí)到自己的程序中。 本規(guī)范主要針對 C#程序員，但是其中許多規(guī)則同時(shí)適用于其他語言的程序員。 3總總體體要要求求 3.1程程序序結(jié)結(jié)構(gòu)構(gòu)化化 程序結(jié)構(gòu)清晰，函數(shù)功能簡單易懂（單個(gè)函數(shù)的代碼行數(shù)不超過 100 行） 3.2代代碼碼可可讀讀性性 保持注釋與代碼完全一致 每個(gè)源程

6、序文件，都有文件頭說明，詳細(xì)見下節(jié) 每個(gè)函數(shù)，都有函數(shù)頭說明，詳細(xì)見下節(jié) 主要變量（結(jié)構(gòu)、聯(lián)合、類或?qū)ο螅┒x或引用時(shí)，注釋能反映其含義 處理過程的每個(gè)階段都有相關(guān)注釋說明 在典型算法前都有注釋, 同時(shí)算法在滿足要求的情況下盡可能簡單 利用縮進(jìn)來顯示程序的邏輯結(jié)構(gòu)，縮進(jìn)量一致并以 Tab 鍵為單位，定義 Tab 為 4 個(gè)字節(jié) 循環(huán)、分支層次一般不應(yīng)超過五層 代碼簡單的分支應(yīng)該寫在前面 不允許同行出現(xiàn)兩個(gè)語句 空行和空白字符也是一種特殊注釋 一目了然的語句不加注釋 注釋的作用范圍可以為：定義、引用、條件分支以及一段代碼 常量定義（DEFINE）有相應(yīng)說明 3.3代代碼碼結(jié)結(jié)構(gòu)構(gòu)化化 禁止 GO

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

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

9、xpr1, expr2, 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ī)范的，它換行在括號外面（較高層）。 另外請注意，換行后的新行應(yīng)使用 tab 和空格保持與前一行的同級運(yùn)算符對 齊，例如: var = a * b / (c - g + f) + .4 * z; 表示 Tab 符， .表示空格。你可以設(shè)置你的編輯環(huán)境，使 Tab 和空格 在編輯時(shí)是可見的，這是一個(gè)不錯(cuò)的習(xí)慣。 4.2

10、.2空格 我們選擇 Tab 縮進(jìn)作為縮進(jìn)時(shí)采用的標(biāo)準(zhǔn)。 請不要使用空格代替請不要使用空格代替 Tab 鍵鍵! 4.3注注釋釋 4.3.1 模塊注釋 在一個(gè)程序模塊的開始，應(yīng)用注釋說明模塊的名字、功能、開發(fā)者和日期和版本變更 歷史，如下所示： /* * Copyright(c) Suzsoft DotNet Group * Description : Tenant access class * CreateDate : 2006-06-02 05:03:46 * Creater : Johnson Cao * LastChangeDate: * LastChanger : * Version I

11、nfo : 1.0 * */ 4.3.2單行注釋 程序員應(yīng)當(dāng)在算法比較復(fù)雜的表達(dá)式前、特殊含義的變量前或者在一整段功能 代碼開始之前添加適當(dāng)?shù)淖⑨?。我們要求這樣的單行 注釋采用”/”符號，例如： / Calculate subTotal Decimal subTotal = 0; 4.3.3類注釋 在定義一個(gè)類之前，應(yīng)用“/”注釋說明類的功能、使用方法和特殊的屬性，如下所 示： / / This class. / / Please note / / 詳細(xì)的 xml 注釋標(biāo)記的使用請參見附錄。 4.3.4方法注釋 在定義類成員方法前，應(yīng)說明該過程/函數(shù)的名字、功能、輸入/輸出和版本變更歷史， 如

12、下所示： / / This method . / this is a param of the method SomeMethod. / a return object / /- / 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)檫@樣你可以在聲明后面寫上該變量的注釋，例如：

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

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

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

16、 IntList) . 注意：即使循環(huán)中只有一句執(zhí)行語句，我們也要求使用注意：即使循環(huán)中只有一句執(zhí)行語句，我們也要求使用” 4.5.4While/do-while 語句 While 循環(huán)格式： while (condition) . 對于空循環(huán)可以這樣寫： while (condition) ; do-while 循環(huán)格式： do . while(condition); 4.5.5Switch 語句 switch 格式： switch (condition) case A: . break; case B: . break; default: . break; 4.5.6Try-catch 語

17、句 try-catch 格式： try . catch (Exception) 或者： try . catch (Exception e) . 或者： try . catch (Exception e) . finally . 4.6空空白白 4.6.1空白行 空白行有增強(qiáng)可讀性的作用。它們隔離了邏輯上相互獨(dú)立的模塊。 在下列情況中我們還可以使用雙空白行： 源文件中的兩個(gè)獨(dú)立的邏輯片斷之間 類和接口之間（但一般情況下我們還是建議一個(gè)文件一個(gè)類或接口） 下列情況中我們可以使用單空白行： 方法之間 屬性之間 方法內(nèi)局部變量第一出聲明前 方法內(nèi)相對獨(dú)立的邏輯之間 注意，盡量保持空白行和其他行具有同樣

18、的縮進(jìn)，可以使今后插入代碼能夠保 持相同的縮進(jìn)。 4.6.2參數(shù)條件之間的空白 通過這些空白，可以使代碼更容易被閱讀，例如： TestMethod(a, b, c); 而不應(yīng)該這樣： TestMethod(a,b,c) 但是也不應(yīng)有過多的空格，比如： TestMethod( a, b, c ); 操作符和變量或數(shù)字之間應(yīng)該有空格： a = b; / dont use a=b; for (int i = 0; i 10; +i) / dont use for (int i=0; i10; +i) / or / for(int i=0;i10;+i) 4.6.3表格式的樣式 連續(xù)的多行付值語句可以

19、這樣子寫： string strName = Mr. Ed; int nValue = 5; Test aTest = Test.TestYou; 利用空格對齊所有的“=”，使代碼塊看起來像表格一樣。 4.7命命名名規(guī)規(guī)范范 4.7.1大寫 Pascal 風(fēng)格 變量的首字母大寫，如：Name 駝峰規(guī)則 除了首個(gè)單詞，每個(gè)單詞的首字母大寫，如：TestName 大寫風(fēng)格 只在少于兩個(gè)字母的縮寫中使用大寫。三個(gè)以上字母的縮寫都應(yīng)該使用 PASCAL 風(fēng)格。 4.7.2命名方法 通常我們采用匈牙利命名法來為變量命名。 匈牙利命名法通常采用變量類型的縮寫作為

20、前綴，變量含義的全拼作為后綴 的方法來命名變量。這種命名方法被廣泛的采用在 windows 程序開發(fā)中，它因 由一匈牙利程序員創(chuàng)立而得名。 注意：好的變量命名不是突出其類型，而是突出其含義。 對于對于 UI 控件，我們強(qiáng)制要求縮寫前綴控件，我們強(qiáng)制要求縮寫前綴，例如： System.Windows.Forms.Button btnCancel; System.Windows.Forms.TextBox txtName; 類命名 使用名詞或名詞短語命名類。 使用 Pascal 風(fēng)格. 謹(jǐn)慎使用縮寫命名類。. 不要使用任何類前綴（如 C）. 接口命名 使用名詞或名詞短語

21、命名接口.(例如 IComponent 或 IEnumberable) 使用 Pascal 風(fēng)格 使用大寫的 I 作為首字母，表示為接口 枚舉命名 使用 Pascal 風(fēng)格 不使用前綴 使用單數(shù)名詞命名 常量命名 采用有意義的單詞命名 使用全部大寫字母拼寫 參數(shù)命名 相對變量而言，參數(shù)更注重本身的含義作為命名 使用駝峰規(guī)則命名 變量命名 作為循環(huán)中的運(yùn)算子的變量，更適合采用簡單的命名，如 i, j, k, l, m, n 方法命名 采用動(dòng)詞命名，或者動(dòng)詞詞組 使用 Pascal 風(fēng)格 屬性命名 使用名詞或名詞短

22、語命名屬性 使用 Pascal 風(fēng)格 事件命名 使用 EventHandler 作為事件句柄的后綴 使用兩個(gè)參數(shù)：sender 和 e 使用 Pascal 風(fēng)格 使用 EventArgs 作為 Event Argument 類型名的后綴 使用進(jìn)行時(shí)動(dòng)詞和過去式動(dòng)詞作為事件的名稱 0 大寫風(fēng)格 TypeCaseNotes Class / StructPascal Casing InterfacePascal CasingStarts with I Enum valuesPascal Casing Enum typePascal Casing EventsPascal

23、Casing Exception classPascal CasingEnd with Exception public FieldsPascal Casing MethodsPascal Casing NamespacePascal Casing PropertyPascal Casing Protected/private FieldsCamel Casing ParametersCamel Casing 4.8開開發(fā)發(fā)習(xí)習(xí)慣慣 4.8.1可見性 請避免將類變量或一個(gè)實(shí)例聲明為公共類型的變量，而應(yīng)該將其聲明為私有變 量。 如果你確實(shí)需要公開一個(gè)類變量或者實(shí)例的話，可以使 990 用屬性(P

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

25、MeClass Test test; public Test Test get return test; set test = value; void DoSomething() if (test = Test.TestMe) /.stuff gets done else /.other stuff gets done 作用域（”）應(yīng)該在下列代碼后另起一行開始： Namespace 聲明后 Class/ Interface / Struct 的聲明后 Method 聲明后 循環(huán)或者判斷(ifelse)后 5參參考考 6附附錄錄 6.1XML注注釋釋標(biāo)標(biāo)記記的的使使用用 6.1.1Section

26、 標(biāo)記 Section 標(biāo)記用于定義不同的代碼文檔的區(qū)域。它們都是頂級標(biāo)記，Block 標(biāo)記、Inline 標(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)記標(biāo)記說明說明 NDoc 擴(kuò)充擴(kuò)充 對某個(gè)成員可能引發(fā)的事件的說明。 “示例”，幫助類庫使用者理解類型/成員使用方法的示例代碼。 對某個(gè)成員可以拋出的異常的說明。 NDoc 擴(kuò)充擴(kuò)充 指示 NDoc 文檔引擎將被標(biāo)記的類型/成員排除在代碼文檔之外。 與文檔引擎的“可見性”配置不符的，以 exclude 優(yōu)先。 將代

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

28、s hello. public void SayHello() . /This one says hello to someone. public void SayHello(string toSomeone) . 成員的參數(shù)說明。 訪問某成員所必需的 .NET Framework 安全性 CodeAccessPermission。 NDoc 擴(kuò)充擴(kuò)充 將某類型/成員標(biāo)記為“預(yù)發(fā)布”。內(nèi)部的文本被當(dāng)作警告文本用紅色顯示，可以 包含 表示多行文本。如果缺少內(nèi)部文本，則顯示默認(rèn)的警告文本: “此文檔 為預(yù)發(fā)布版本，在未來版本中有可能改變?！?。 如果需要把全部類型/成員都標(biāo)記為“預(yù)發(fā)布”，請使用文檔引擎的 Preliminary 配置項(xiàng)。 “備注”，對 的進(jìn)一步注解。 “返回值”。 向頁面的“請參見”區(qū)域添加一個(gè)鏈接。 請不要請不要將此標(biāo)記包含在 內(nèi)部，它是一個(gè)頂