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

1、請(qǐng)預(yù)覽后下載！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 elec

2、tronically via a Document Change Order (DCO).目錄目錄請(qǐng)預(yù)覽后下載！1目標(biāo)目標(biāo) .42概述概述 .43總體要求總體要求 .43.1程序結(jié)構(gòu)化.43.2代碼可讀性.43.3代碼結(jié)構(gòu)化.53.4正確性與容錯(cuò)性.53.5可重用性.54編碼規(guī)范編碼規(guī)范 .64.1文件結(jié)構(gòu).64.1.1C# 文件.64.1.2目錄結(jié)構(gòu).64.2縮進(jìn).64.2.1換行.64.2.2空格.74.3注釋.74.3.1模塊注釋.74.3.2單行注釋.84.3.3類注釋.84.3.4方法注釋.84.4聲明.94.4.1單行聲明變量數(shù).94.4.2初始化.94.4.3類和接口聲明.94.

3、5功能語(yǔ)句.104.5.1簡(jiǎn)單邏輯.104.5.2返回語(yǔ)句.104.5.3if-else語(yǔ)句.104.5.4For / Foreach 語(yǔ)句.114.5.5While/do-while 語(yǔ)句.114.5.6Switch 語(yǔ)句.114.5.7Try-catch 語(yǔ)句.124.6空白.124.6.1空白行.124.6.2參數(shù)條件之間的空白.134.6.3表格式的樣式.134.7命名規(guī)范.144.7.1大寫.Pascal 風(fēng)格.駝峰規(guī)則.大寫風(fēng)格.144.7.2命名方法.類命名.接口命名.枚舉

4、命名.常量命名.參數(shù)命名.15請(qǐng)預(yù)覽后下載！變量命名.方法命名.屬性命名.事件命名.0大寫風(fēng)格.164.8開發(fā)習(xí)慣.164.8.1可見性.164.8.2不要硬編碼數(shù)字.174.9代碼示例.174.9.1作用域（“”）示例.175參考參考 .186附錄附錄 .186.1XML 注釋標(biāo)記的使用.187修改歷史修改歷史 .22請(qǐng)預(yù)覽后下載！1目目標(biāo)標(biāo)為新宇 DotNet 組的 C#程序員制定一個(gè)統(tǒng)一的編碼規(guī)范，最大限度減少不同程序員開發(fā)的代碼間的差異。2概概述述 為了使應(yīng)用程序的

5、結(jié)構(gòu)和編碼風(fēng)格標(biāo)準(zhǔn)化，便于閱讀和理解編碼，以提高開發(fā)效率和產(chǎn)品的標(biāo)準(zhǔn)化，制訂一套開發(fā)規(guī)范和標(biāo)準(zhǔn)勢(shì)在必行。此外，好的編碼約定可使源代碼嚴(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é)結(jié)構(gòu)構(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ū)?/p>

6、象）定義或引用時(shí)，注釋能反映其含義處理過程的每個(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é)結(jié)構(gòu)構(gòu)化化禁止 GOTO 語(yǔ)句用 CASE 實(shí)現(xiàn)多路分支避免不必要的分支用 IF 語(yǔ)句來強(qiáng)調(diào)只執(zhí)行兩組語(yǔ)句中的一組。盡量不使用 ELSE RETUR

7、N 盡量避免從循環(huán)引出多個(gè)出口請(qǐng)預(yù)覽后下載！3.4正正確確性性與與容容錯(cuò)錯(cuò)性性所有變量在調(diào)用前必須被初始化不要比較浮點(diǎn)數(shù)的相等，如： 10.0 * 0.1 = 1.0 ， 不可靠訪問外部資源(數(shù)據(jù)庫(kù)，外部文件)時(shí)使用規(guī)范的容錯(cuò)語(yǔ)句例如:trycatchfinally4編編碼碼規(guī)規(guī)范范4.1文文件件結(jié)結(jié)構(gòu)構(gòu)4.1.1C# 文件盡量不要讓你的類或者文件太長(zhǎng),一般不應(yīng)超過 2000 行代碼。請(qǐng)按照功能劃分你的代碼，使結(jié)構(gòu)保持清晰。一般情況下，一個(gè)文件應(yīng)當(dāng)只有一個(gè)類，并且文件名應(yīng)該與類名保持一致。 4.1.2目錄結(jié)構(gòu)應(yīng)該為每個(gè)名稱空間(namespace)建立一個(gè)目錄(例如，我們可以為名稱空間MyPr

8、oject.TestSuite.TestTier 建立這樣的目錄：MyProject/TestSuite/TestTier)。這樣做可以讓你很快定位到指定名稱空間下的類文件。 4.2縮縮進(jìn)進(jìn)4.2.1換行如果表達(dá)式太長(zhǎng)而一行無法寫下時(shí)，請(qǐng)按照下列規(guī)范進(jìn)行換行： 可以在逗號(hào)后面進(jìn)行換行 可以在操作符號(hào)后進(jìn)行換行 盡量選擇在較高層處進(jìn)行換行 換行后的新行應(yīng)當(dāng)與前一行中同級(jí)別的運(yùn)算符對(duì)齊 請(qǐng)預(yù)覽后下載！例子：方法調(diào)用換行： longMethodCall(expr1, expr2, expr3, expr4, expr5); 算術(shù)表達(dá)式換行：規(guī)范的:var = a * b / (c - g + f)

9、+ 4 * z;不規(guī)范的:var = a * b / (c - g + f) + 4 * z; 上面第一個(gè)表達(dá)式的換行方式是符合規(guī)范的，它換行在括號(hào)外面（較高層）。另外請(qǐng)注意，換行后的新行應(yīng)使用 tab 和空格保持與前一行的同級(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)不要使用空格代替請(qǐng)不要使用空格代替 TabTab 鍵鍵!4.3注注釋釋4.3.1 模塊注釋在一個(gè)程序模塊的

10、開始，應(yīng)用注釋說明模塊的名字、功能、開發(fā)者和日期和版本變更歷史，如下所示：/* * Copyright(c) Suzsoft DotNet Group * Description : Tenant access class * CreateDate : 2006-06-02 05:03:46 * Creater : Johnson Cao * LastChangeDate: * LastChanger : 請(qǐng)預(yù)覽后下載！ * Version Info : 1.0 * */ 4.3.2單行注釋程序員應(yīng)當(dāng)在算法比較復(fù)雜的表達(dá)式前、特殊含義的變量前或者在一整段功能代碼開始之前添加適當(dāng)?shù)淖⑨?。我們要?/p>

11、這樣的單行 注釋采用”/”符號(hào)，例如：/ Calculate subTotalDecimal subTotal = 0;4.3.3類注釋在定義一個(gè)類之前，應(yīng)用“/”注釋說明類的功能、使用方法和特殊的屬性，如下所示：/ / This class./ / Please note / / 詳細(xì)的 xml 注釋標(biāo)記的使用請(qǐng)參見附錄。 4.3.4方法注釋在定義類成員方法前，應(yīng)說明該過程/函數(shù)的名字、功能、輸入/輸出和版本變更歷史，如下所示：/ / This method ./ this is a param of the method SomeMethod./ a return object/ /-/

12、Change History:/ DateWho Changes Made/ 2000-5-1Author1Initial creation/ 2000-5-15Author2Add some code/-public object SomeMethod(object param1)請(qǐng)預(yù)覽后下載！4.4聲聲明明4.4.1 單行聲明變量數(shù)我們推薦每行只聲明一個(gè)變量，因?yàn)檫@樣你可以在聲明后面寫上該變量的注釋，例如：int level; / indentation levelint size; / size of table請(qǐng)不要在同一行聲明不同含義的變量，比如： int a, b; /What i

13、s a? What does b stand for?上面的例子同樣可以說明了沒有意義的變量名稱會(huì)讓人很難理解，因此，在定義變量的時(shí)候，我們一定要給它們一個(gè)有含義的名字。 4.4.2 初始化最好在一定義后就初始化變量，例如：string name = strObject.Name;or int val = time.Hours;注意：如果你想要初始化對(duì)話框變量，建議使用 using 聲明方式例如：using (OpenFileDialog openFileDialog = new OpenFileDialog() .4.4.3類和接口聲明在聲明類和接口的時(shí)候應(yīng)當(dāng)遵照下列規(guī)范： 方法名稱和放置參

14、數(shù)的括號(hào)”(”之間不應(yīng)該有空格 類名聲明之后應(yīng)另起一行寫作用域開始符” 作用域結(jié)束符”應(yīng)當(dāng)單獨(dú)占一行，并與對(duì)應(yīng)的開始符”處在同一縮進(jìn)位置上 示例： Class MySample : MyClass, IMyInterface請(qǐng)預(yù)覽后下載！int myInt;public MySample(int myInt)this.myInt = myInt ;void Inc()+myInt;void EmptyMethod()4.5功功能能語(yǔ)語(yǔ)句句4.5.1簡(jiǎn)單邏輯每一行代碼應(yīng)當(dāng)只實(shí)現(xiàn)一個(gè)邏輯 4.5.2if-else語(yǔ)句if-else 應(yīng)該按照這種格式書寫：if(condition) DoSometh

15、ing();. else DoSomethingOther();.4.5.3For / 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) 請(qǐng)預(yù)覽后下載！.注意：即使循環(huán)中只有一句執(zhí)行語(yǔ)句，我們也要求使用注意：即使循環(huán)中只有一句執(zhí)行語(yǔ)句，我們也要求使用” 4.5.4While/do-while 語(yǔ)句While 循環(huán)格式： while (condition)

16、.對(duì)于空循環(huán)可以這樣寫：while (condition) ;do-while 循環(huán)格式：do .while(condition);4.5.5Switch 語(yǔ)句switch 格式： switch (condition) case A:.break;case B:.break;default:.break;4.5.6Try-catch 語(yǔ)句try-catch 格式： try . catch (Exception) 請(qǐng)預(yù)覽后下載！或者：try . catch (Exception e) .或者：try . catch (Exception e) . finally .4.6空空白白4.6.1空白行

17、空白行有增強(qiáng)可讀性的作用。它們隔離了邏輯上相互獨(dú)立的模塊。在下列情況中我們還可以使用雙空白行： 源文件中的兩個(gè)獨(dú)立的邏輯片斷之間類和接口之間（但一般情況下我們還是建議一個(gè)文件一個(gè)類或接口）下列情況中我們可以使用單空白行： 方法之間 屬性之間方法內(nèi)局部變量第一出聲明前 方法內(nèi)相對(duì)獨(dú)立的邏輯之間 注意，盡量保持空白行和其他行具有同樣的縮進(jìn)，可以使今后插入代碼能夠保持相同的縮進(jìn)。 請(qǐng)預(yù)覽后下載！4.6.2參數(shù)條件之間的空白通過這些空白，可以使代碼更容易被閱讀，例如：TestMethod(a, b, c); 而不應(yīng)該這樣： TestMethod(a,b,c)但是也不應(yīng)有過多的空格，比如：TestMet

18、hod( 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ù)的多行付值語(yǔ)句可以這樣子寫：string strName = Mr. Ed;int nValue = 5;Test aTest = Test.TestYou;利用空格對(duì)齊所有的“=”，使代碼塊看起來像表格一樣。 4.7命命名名規(guī)規(guī)范范4.7.1大寫Pascal 風(fēng)格變量的首字母大寫，

19、如：Name駝峰規(guī)則除了首個(gè)單詞，每個(gè)單詞的首字母大寫，如：TestName請(qǐng)預(yù)覽后下載！ 大寫風(fēng)格只在少于兩個(gè)字母的縮寫中使用大寫。三個(gè)以上字母的縮寫都應(yīng)該使用 PASCAL 風(fēng)格。4.7.2命名方法通常我們采用匈牙利命名法來為變量命名。 匈牙利命名法通常采用變量類型的縮寫作為前綴，變量含義的全拼作為后綴的方法來命名變量。這種命名方法被廣泛的采用在 windows 程序開發(fā)中，它因由一匈牙利程序員創(chuàng)立而得名。 注意：好的變量命名不是突出其類型，而是突出其含義。 對(duì)于對(duì)于 UIUI 控件，我們強(qiáng)制要求縮寫前綴控件，我們強(qiáng)制要求縮寫前綴，例如：System.Windo

20、ws.Forms.Button btnCancel;System.Windows.Forms.TextBox txtName;類命名使用名詞或名詞短語(yǔ)命名類。使用 Pascal 風(fēng)格.謹(jǐn)慎使用縮寫命名類。.不要使用任何類前綴（如 C）.接口命名使用名詞或名詞短語(yǔ)命名接口.(例如 IComponent 或 IEnumberable) 使用 Pascal 風(fēng)格使用大寫的 I 作為首字母，表示為接口 枚舉命名使用 Pascal 風(fēng)格不使用前綴 使用單數(shù)名詞命名 常量命名采用有意義的單詞命名 使用全部大寫字母拼寫請(qǐng)預(yù)覽后下載！參數(shù)命

21、名相對(duì)變量而言，參數(shù)更注重本身的含義作為命名 使用駝峰規(guī)則命名 變量命名作為循環(huán)中的運(yùn)算子的變量，更適合采用簡(jiǎn)單的命名，如 i, j, k, l, m, n 方法命名采用動(dòng)詞命名，或者動(dòng)詞詞組 使用 Pascal 風(fēng)格屬性命名使用名詞或名詞短語(yǔ)命名屬性 使用 Pascal 風(fēng)格事件命名使用 EventHandler 作為事件句柄的后綴 使用兩個(gè)參數(shù)：sender 和 e 使用 Pascal 風(fēng)格使用 EventArgs 作為 Event Argument 類型名的后綴使用進(jìn)行時(shí)動(dòng)詞和過去式動(dòng)詞作為事件的名稱 0 大寫風(fēng)格Ty

22、peCaseNotesClass / StructPascal Casing InterfacePascal CasingStarts with IEnum valuesPascal Casing Enum typePascal Casing EventsPascal Casing Exception classPascal CasingEnd with Exceptionpublic FieldsPascal Casing MethodsPascal Casing NamespacePascal Casing PropertyPascal Casing 請(qǐng)預(yù)覽后下載！Protected/pr

23、ivate FieldsCamel Casing 請(qǐng)預(yù)覽后下載！ParametersCamel Casing 4.8開開發(fā)發(fā)習(xí)習(xí)慣慣4.8.1可見性請(qǐng)避免將類變量或一個(gè)實(shí)例聲明為公共類型的變量，而應(yīng)該將其聲明為私有變量。如果你確實(shí)需要公開一個(gè)類變量或者實(shí)例的話，可以使 990 用屬性(Property)來公開它。4.8.2不要硬編碼數(shù)字也就是說，在你的邏輯代碼中，不要采用數(shù)字直接參與計(jì)算，尤其是那些可能需要改變的數(shù)字。你應(yīng)該將它付值給一個(gè)常量，使用該常量參與計(jì)算。這樣做得好處是，如果這個(gè)數(shù)字改變的時(shí)候，你不必在代碼中將他找出并修改，而只需修改常量的值。public class MyMathpu

24、blic const double PI = 3.14159.4.9代代碼碼示示例例4.9.1作用域（“”）示例namespace ShowMeTheBracketpublic enum Test TestMe,TestYoupublic class TestMeClassTest test;public Test Test get return test;請(qǐng)預(yù)覽后下載！set test = value;void DoSomething()if (test = Test.TestMe) /.stuff gets done else /.other stuff gets done作用域（”）應(yīng)該

25、在下列代碼后另起一行開始：Namespace 聲明后 Class/ Interface / Struct 的聲明后 Method 聲明后 循環(huán)或者判斷(ifelse)后5參參考考 6附附錄錄6.1X XM ML L注注釋釋標(biāo)標(biāo)記記的的使使用用6.1.1Section 標(biāo)記Section 標(biāo)記用于定義不同的代碼文檔的區(qū)域。它們都是頂級(jí)標(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)記說明說明NDocNDoc 擴(kuò)充擴(kuò)充 對(duì)某個(gè)成員可

26、能引發(fā)的事件的說明?！笆纠?，幫助類庫(kù)使用者理解類型/成員使用方法的示例代碼。對(duì)某個(gè)成員可以拋出的異常的說明。請(qǐng)預(yù)覽后下載！標(biāo)記標(biāo)記說明說明NDocNDoc 擴(kuò)充擴(kuò)充 指示 NDoc 文檔引擎將被標(biāo)記的類型/成員排除在代碼文檔之外。與文檔引擎的“可見性”配置不符的，以 exclude 優(yōu)先。將代碼文件外部的某 XML 文件中的一部分包含進(jìn)代碼文件來。NDocNDoc 擴(kuò)充擴(kuò)充 為“重載列表”頁(yè)面準(zhǔn)備摘要、備注、示例等文檔內(nèi)容。只需在重載成員的第一個(gè)成員前面書寫此區(qū)域即可。 標(biāo)記有兩種形式:簡(jiǎn)單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁(yè)面的摘要。沒有備注、示例等區(qū)

27、域。 復(fù)雜的形式，在 overload 內(nèi)部，包含 summary, remarks, example 等標(biāo)記分別表示“重載列表”頁(yè)面的摘要、備注、示例等。 示例:/This method has two overloads./This overload just says hello.public void SayHello() . /This one says hello to someone.public void SayHello(string toSomeone) . 成員的參數(shù)說明。訪問某成員所必需的 .NET Framework 安全性 CodeAccessPermissionC

28、odeAccessPermission。NDocNDoc 擴(kuò)充擴(kuò)充 將某類型/成員標(biāo)記為“預(yù)發(fā)布”。內(nèi)部的文本被當(dāng)作警告文本用紅色顯示，可以包含 表示多行文本。如果缺少內(nèi)部文本，則顯示默認(rèn)的警告文本: “此文檔為預(yù)發(fā)布版本，在未來版本中有可能改變?！薄?如果需要把全部類型/成員都標(biāo)記為“預(yù)發(fā)布”，請(qǐng)使用文檔引擎的 PreliminaryPreliminary 配置項(xiàng)?！皞渥ⅰ?，對(duì) 的進(jìn)一步注解。“返回值”。向頁(yè)面的“請(qǐng)參見”區(qū)域添加一個(gè)鏈接。請(qǐng)不要請(qǐng)不要將此標(biāo)記包含在 內(nèi)部，它是一個(gè)頂級(jí)標(biāo)記。兩種可選的語(yǔ)法:MSDN(CHS) DataSet “摘要”，對(duì)類型/成員的摘要說明?！熬€程安全”，說明類型在多線程環(huán)境中是否安全。請(qǐng)預(yù)覽后下載！標(biāo)記標(biāo)記說明說明NDocNDoc 擴(kuò)充擴(kuò)充 NDoc