軟件代碼編寫規(guī)范

1、.軟件代碼編寫規(guī)范草稿2005.2.1 命名規(guī)則1.1.Net命名規(guī)則一致的命名模式是托管類庫(kù)中可預(yù)知性與可發(fā)現(xiàn)性最重要的元素之一。對(duì)這些命名指南廣泛的使用和理解將消除許多最常見的用戶問題。本主題提供 .NET Framework 類型的命名指南。對(duì)于每個(gè)類型，還應(yīng)該注意關(guān)于大寫樣式、區(qū)分大小寫和措詞的一些通用規(guī)則。1.1.1大寫樣式 描述用于在類庫(kù)中命名標(biāo)識(shí)符的 Pascal 大小寫、Camel 大小寫和全部大寫樣式。 使用下面的三種大寫標(biāo)識(shí)符約定。l Pascal 大小寫將標(biāo)識(shí)符的首字母和后面連接的每個(gè)單詞的首字母都大寫?？梢詫?duì)三字符或更多字符的標(biāo)識(shí)符使用 Pascal 大小寫。例如：Ba

2、ckColorl Camel 大小寫標(biāo)識(shí)符的首字母小寫，而每個(gè)后面連接的單詞的首字母都大寫。例如：backColorl 大寫標(biāo)識(shí)符中的所有字母都大寫。僅對(duì)于由兩個(gè)或者更少字母組成的標(biāo)識(shí)符使用該約定。例如：System.IOSystem.Web.UI可能還必須大寫標(biāo)識(shí)符以維持與現(xiàn)有非托管符號(hào)方案的兼容性，在該方案中所有大寫字母經(jīng)常用于枚舉和常數(shù)值。一般情況下，在使用它們的程序集之外這些字符應(yīng)當(dāng)是不可見的。下表匯總了大寫規(guī)則，并提供了不同類型的標(biāo)識(shí)符的示例。標(biāo)識(shí)符大小寫示例類PascalAppDomain枚舉類型PascalErrorLevel枚舉值PascalFatalError事件Pascal

3、ValueChange異常類PascalWebException 注意總是以 Exception 后綴結(jié)尾。只讀的靜態(tài)字段PascalRedValue接口PascalIDisposable 注意總是以 I 前綴開始。方法PascalToString命名空間PascalSystem.Drawing參數(shù)CameltypeName屬性PascalBackColor受保護(hù)的實(shí)例字段CamelredValue 注意很少使用。屬性優(yōu)于使用受保護(hù)的實(shí)例字段。公共實(shí)例字段PascalRedValue 注意很少使用。屬性優(yōu)于使用公共實(shí)例字段。1.1.2區(qū)分大小寫為了避免混淆和保證跨語(yǔ)言交互操作，請(qǐng)遵循有關(guān)區(qū)分大

4、小寫的使用的下列規(guī)則： 不要使用要求區(qū)分大小寫的名稱。對(duì)于區(qū)分大小寫和不區(qū)分大小寫的語(yǔ)言，組件都必須完全可以使用。不區(qū)分大小寫的語(yǔ)言無(wú)法區(qū)分同一上下文中僅大小寫不同的兩個(gè)名稱。因此，在創(chuàng)建的組件或類中必須避免這種情況。 不要?jiǎng)?chuàng)建僅是名稱大小寫有區(qū)別的兩個(gè)命名空間。例如，不區(qū)分大小寫的語(yǔ)言無(wú)法區(qū)分以下兩個(gè)命名空間聲明。 namespace ee.cummings;namespace Ee.Cummings; 不要?jiǎng)?chuàng)建具有僅是大小寫有區(qū)別的參數(shù)名稱的函數(shù)。下面的示例是不正確的。 void MyFunction(string a, string A) 不要?jiǎng)?chuàng)建具有僅是大小寫有區(qū)別的類型名稱的命名空間

5、。在下面的示例中，Point p 和 POINT p 是不適當(dāng)?shù)念愋兔Q，原因是它們僅在大小寫方面有區(qū)別。 System.Windows.Forms.Point pSystem.Windows.Forms.POINT p 不要?jiǎng)?chuàng)建具有僅是大小寫有區(qū)別的屬性名稱的類型。在下面的示例中，int Color 和 int COLOR 是不適當(dāng)?shù)膶傩悦Q，原因是它們僅在大小寫方面有區(qū)別。 int Color get, setint COLOR get, set 不要?jiǎng)?chuàng)建具有僅是大小寫有區(qū)別的方法名稱的類型。在下面的示例中，calculate 和 Calculate 是不適當(dāng)?shù)姆椒Q，原因是它們僅在大小

6、寫方面有區(qū)別。 void calculate()void Calculate()1.1.3縮寫為了避免混淆和保證跨語(yǔ)言交互操作，請(qǐng)遵循有關(guān)區(qū)縮寫的使用的下列規(guī)則： 不要將縮寫或縮略形式用作標(biāo)識(shí)符名稱的組成部分。例如，使用 GetWindow，而不要使用 GetWin。 不要使用計(jì)算機(jī)領(lǐng)域中未被普遍接受的縮寫。 在適當(dāng)?shù)臅r(shí)候，使用眾所周知的縮寫替換冗長(zhǎng)的詞組名稱。例如，用 UI 作為 User Interface 的縮寫，用 OLAP 作為 On-line Analytical Processing 的縮寫。 在使用縮寫時(shí)，對(duì)于超過兩個(gè)字符長(zhǎng)度的縮寫，請(qǐng)使用 Pascal 大小寫或 Camel

7、大小寫。例如，使用 HtmlButton 或 htmlButton。但是，應(yīng)當(dāng)大寫僅有兩個(gè)字符的縮寫，如，System.IO，而不是 System.Io。 不要在標(biāo)識(shí)符或參數(shù)名稱中使用縮寫。如果必須使用縮寫，對(duì)于由多于兩個(gè)字符所組成的縮寫請(qǐng)使用 Camel 大小寫，雖然這和單詞的標(biāo)準(zhǔn)縮寫相沖突。 1.1.4措詞避免使用與常用的 .NET Framework 命名空間重復(fù)的類名稱。例如，不要將以下任何名稱用作類名稱：System、Collections、Forms 或 UI。有關(guān) .NET Framework 命名空間的列表，請(qǐng)參見類庫(kù)。另外，避免使用和以下關(guān)鍵字沖突的標(biāo)識(shí)符。AddHandle

8、rAddressOfAliasAndAnsiAsAssemblyAutoBaseBooleanByRefByteByValCallCaseCatchCBoolCByteCCharCDateCDecCDblCharCIntClassCLngCObjConstCShortCSngCStrCTypeDateDecimalDeclareDefault1.1.5避免類型名稱混淆語(yǔ)言 不同的編程語(yǔ)言使用不同的術(shù)語(yǔ)標(biāo)識(shí)基本托管類型。類庫(kù)設(shè)計(jì)人員必須避免使用語(yǔ)言特定的術(shù)語(yǔ)。請(qǐng)遵循本節(jié)中描述的規(guī)則以避免類型名稱混淆。使用描述類型的含義的名稱，而不是描述類型的名稱。如果參數(shù)除了其類型之外沒有任何語(yǔ)義含義，那么在這

9、種罕見的情況下請(qǐng)使用一般性名稱。例如，支持將各種數(shù)據(jù)類型寫入到流中的類可以有以下方法。VisualBasicSub Write(value As Double);Sub Write(value As Single);Sub Write(value As Long);Sub Write(value As Integer);Sub Write(value As Short);C#void Write(double value);void Write(float value);void Write(long value);void Write(int value);void Write(short

10、value);不要?jiǎng)?chuàng)建語(yǔ)言特定的方法名稱，如下面的示例所示。VisualBasicSub Write(doubleValue As Double);Sub Write(singleValue As Single);Sub Write(longValue As Long);Sub Write(integerValue As Integer);Sub Write(shortValue As Short);C#void Write(double doubleValue);void Write(float floatValue);void Write(long longValue);void Writ

11、e(int intValue);void Write(short shortValue);如果有必要為每個(gè)基本數(shù)據(jù)類型創(chuàng)建唯一命名的方法，那么在這種極為罕見的情況下請(qǐng)使用通用類型名稱。下表列出基本數(shù)據(jù)類型名稱和它們的通用替換。C# 類型名稱Visual Basic 類型名稱JScript 類型名稱Visual C+ 類型名稱Ilasm.exe 表示形式通用類型名稱sbyteSBytesBytecharint8SBytebyteBytebyteunsigned charunsigned int8ByteshortShortshortshortint16Int16ushortUInt16ushor

12、tunsigned shortunsigned int16UInt16intIntegerintintint32Int32uintUInt32uintunsigned intunsigned int32UInt32longLonglong_int64int64Int64ulongUInt64ulongunsigned _int64unsigned int64UInt64floatSinglefloatfloatfloat32SingledoubleDoubledoubledoublefloat64DoubleboolBooleanbooleanboolboolBooleancharCharch

13、arwchar_tcharCharstringStringstringStringstringStringobjectObjectobjectObjectobjectObject例如，支持將從流讀取各種數(shù)據(jù)類型的類可以有以下方法。VisualBasicReadDouble()As DoubleReadSingle()As SingleReadInt64()As LongReadInt32()As IntegerReadInt16()As ShortC#double ReadDouble();float ReadSingle();long ReadInt64();int ReadInt32();

14、short ReadInt16();上面的示例優(yōu)先于下面的語(yǔ)言特定的替代方法。VisualBasicReadDouble()As DoubleReadSingle()As SingleReadLong()As LongReadInteger()As IntegerReadShort()As ShortC#double ReadDouble();float ReadFloat();long ReadLong();int ReadInt();short ReadShort();1.1.6命名空間命名指南命名命名空間時(shí)的一般性規(guī)則是使用公司名稱，后跟技術(shù)名稱和可選的功能與設(shè)計(jì)，如下所示。Compan

15、yName.TechnologyName.Feature.Design例如：Microsoft.MediaMicrosoft.Media.Design給命名空間名稱加上公司名稱或者其他知名商標(biāo)的前綴可以避免兩個(gè)已經(jīng)發(fā)布的命名空間名稱相同的可能性。例如，Microsoft.Office 是由 Microsoft 提供的 Office Automation Classes 的一個(gè)適當(dāng)?shù)那熬Y。在第二級(jí)分層名稱上使用穩(wěn)定的、公認(rèn)的技術(shù)名稱。將組織層次架構(gòu)用作命名空間層次架構(gòu)的基礎(chǔ)。命名一個(gè)命名空間，該命名空間包含為具有 .Design 后綴的基命名空間提供設(shè)計(jì)時(shí)功能的類型。例如，System.Wind

16、ows.Forms.Design 命名空間包含用于設(shè)計(jì)基于 System.Windows.Forms 的應(yīng)用程序的設(shè)計(jì)器和相關(guān)的類。嵌套的命名空間應(yīng)當(dāng)在包含它的命名空間中的類型上有依賴項(xiàng)。例如，System.Web.UI.Design 中的類依賴于 System.Web.UI 中的類。但是，System.Web.UI 中的類不依賴于 System.Web.UI.Design 中的類。應(yīng)當(dāng)對(duì)命名空間使用 Pascal 大小寫，并用句點(diǎn)分隔邏輯組件，如 Microsoft.Office.PowerPoint 中所示。如果您的商標(biāo)使用非傳統(tǒng)的大小寫，請(qǐng)遵循您的商標(biāo)所定義的大小寫，即使它與規(guī)定的 Pa

17、scal 大小寫相背離。例如，命名空間 NeXT.WebObjects 和 ee.cummings 闡釋了對(duì)于 Pascal 大小寫規(guī)則的適當(dāng)背離。如果在語(yǔ)義上適當(dāng)，使用復(fù)數(shù)命名空間名稱。例如，使用 System.Collections 而不是 System.Collection。此規(guī)則的例外是商標(biāo)名稱和縮寫。例如，使用 System.IO 而不是 System.IOs。不要為命名空間和類使用相同的名稱。例如，不要既提供 Debug 命名空間也提供 Debug 類。最后，請(qǐng)注意命名空間名稱不必非得與程序集名稱相似。例如，如果命名程序集 MyCompany.MyTechnology.dll，它沒

18、有必要非得包含 MyCompany.MyTechnology 命名空間。推薦使用的命名空間ISCAS.IEL.MES.ChangLian.MaterBalanceIEL.MES.ChangLian.MaterialBalance1.1.7類命名指南以下規(guī)則概述命名類的指南： 使用名詞或名詞短語(yǔ)命名類。 使用 Pascal 大小寫。 少用縮寫。 不要使用類型前綴，如在類名稱上對(duì)類使用 C 前綴。例如，使用類名稱 ，而不是 C。 不要使用下劃線字符 (_)。 有時(shí)候需要提供以字母 I 開始的類名稱，雖然該類不是接口。只要 I 是作為類名稱組成部分的整個(gè)單詞的第一個(gè)字母，這便是適當(dāng)?shù)?。例如，類名稱

19、IdentityStore 就是適當(dāng)?shù)摹?在適當(dāng)?shù)牡胤?，使用?fù)合單詞命名派生的類。派生類名稱的第二個(gè)部分應(yīng)當(dāng)是基類的名稱。例如，ApplicationException 對(duì)于從名為 Exception 的類派生的類是適當(dāng)?shù)拿Q，原因是 ApplicationException 是一種 Exception。請(qǐng)?jiān)趹?yīng)用該規(guī)則時(shí)進(jìn)行合理的判斷。例如，Button 對(duì)于從 Control 派生的類是適當(dāng)?shù)拿Q。盡管按鈕是一種控件，但是將 Control 作為類名稱的一部分將使名稱不必要地加長(zhǎng)。 下面是正確命名的類的示例。VisualBasicPublic Class Public Class Butto

20、nPublic Class StringC#public class public class Buttonpublic class String1.1.8接口命名指南以下規(guī)則概述接口的命名指南： 用名詞或名詞短語(yǔ)，或者描述行為的形容詞命名接口。例如，接口名稱 IComponent 使用描述性名詞。接口名稱 ICustomAttributeProvider 使用名詞短語(yǔ)。名稱 IPersistable 使用形容詞。 使用 Pascal 大小寫。 少用縮寫。 給接口名稱加上字母 I 前綴，以指示該類型為接口。 在定義類/接口對(duì)（其中類是接口的標(biāo)準(zhǔn)實(shí)現(xiàn)）時(shí)使用相似的名稱。兩個(gè)名稱的區(qū)別應(yīng)該只是接口

21、名稱上有字母 I 前綴。 不要使用下劃線字符 (_)。 以下是正確命名的接口的示例。Visual BasicPublic Interface IServiceProviderPublic Interface IFormatableC#public interface IServiceProviderpublic interface IFormatable以下代碼示例闡釋如何定義 IComponent 接口及其標(biāo)準(zhǔn)實(shí)現(xiàn) Component 類。Visual BasicPublic Interface IComponent Implementation code goes here.End Int

22、erfacePublic Class Component Implements IComponent Implementation code goes here.End ClassC#public interface IComponent / Implementation code goes here.public class Component: IComponent / Implementation code goes here.1.1.9屬性命名指南應(yīng)該總是將后綴 Attribute 添加到自定義屬性類。以下是正確命名的屬性類的示例。VisualBasicPublic Class Obs

23、oleteAttributeC#public class ObsoleteAttribute1.1.10枚舉類型命名指南枚舉 (Enum) 值類型從 Enum 類繼承。以下規(guī)則概述枚舉的命名指南： 對(duì)于 Enum 類型和值名稱使用 Pascal 大小寫。 少用縮寫。 不要在 Enum 類型名稱上使用 Enum 后綴。 對(duì)大多數(shù) Enum 類型使用單數(shù)名稱，但是對(duì)作為位域的 Enum 類型使用復(fù)數(shù)名稱。 總是將 FlagsAttribute 添加到位域 Enum 類型。1.1.11靜態(tài)字段命名指南以下規(guī)則概述靜態(tài)字段的命名指南： 使用名詞、名詞短語(yǔ)或者名詞的縮寫命名靜態(tài)字段。 使用 Pascal

24、 大小寫。 不要在靜態(tài)字段名稱中使用匈牙利語(yǔ)表示法的前綴。 建議盡可能使用靜態(tài)屬性而不是公共靜態(tài)字段。 1.1.12參數(shù)命名指南必須仔細(xì)遵守這些參數(shù)的命名指南，這非常重要，因?yàn)樘峁┥舷挛南嚓P(guān)幫助和類瀏覽功能的可視化設(shè)計(jì)工具會(huì)在設(shè)計(jì)器中對(duì)用戶顯示方法參數(shù)名稱。以下規(guī)則概述參數(shù)的命名指南： 對(duì)參數(shù)名稱使用 Camel 大小寫。 使用描述性參數(shù)名稱。參數(shù)名稱應(yīng)當(dāng)具有足夠的描述性，以便參數(shù)的名稱及其類型可用于在大多數(shù)情況下確定它的含義。例如，提供上下文相關(guān)幫助的可視化設(shè)計(jì)工具會(huì)按開發(fā)人員鍵入的實(shí)際內(nèi)容顯示方法參數(shù)。在這種情況下，方法參數(shù)名稱的表述必須清楚明白，開發(fā)人員才能提供正確的參數(shù)。 使用描述參數(shù)

25、的含義的名稱，而不要使用描述參數(shù)的類型的名稱。開發(fā)工具將提供有關(guān)參數(shù)的類型的有意義的信息。因此，通過描述意義，可以更好地使用參數(shù)的名稱。少用基于類型的參數(shù)名稱，僅在適合使用它們的地方使用它們。 不要使用保留的參數(shù)。保留的參數(shù)是專用參數(shù)，如果需要，可以在未來(lái)的版本中公開它們。相反，如果在類庫(kù)的未來(lái)版本中需要更多的數(shù)據(jù)，請(qǐng)為方法添加新的重載。 不要給參數(shù)名稱加匈牙利語(yǔ)類型表示法的前綴。 以下是正確命名的參數(shù)的示例。VisualBasicGetType(typeName As String)As TypeFormat(format As String, args() As object)As Str

26、ingC#Type GetType(string typeName)string Format(string format, object args)1.1.13方法命名指南以下規(guī)則概述方法的命名指南： 使用動(dòng)詞或動(dòng)詞短語(yǔ)命名方法。 使用 Pascal 大小寫。 以下是正確命名的方法的實(shí)例。RemoveAll()GetCharArray()Invoke()1.1.14屬性命名指南以下規(guī)則概述屬性的命名指南： 使用名詞或名詞短語(yǔ)命名屬性。 使用 Pascal 大小寫。 不要使用匈牙利語(yǔ)表示法。 考慮用與屬性的基礎(chǔ)類型相同的名稱創(chuàng)建屬性。例如，如果聲明名為 Color 的屬性，則屬性的類型同樣應(yīng)該

27、是 Color。請(qǐng)參見本主題內(nèi)下文中的示例。 以下代碼示例闡釋正確的屬性命名。VisualBasicPublic Class SampleClass Public Property BackColor As Color Code for Get and Set accessors goes here. End PropertyEnd ClassC#public class SampleClass public Color BackColor / Code for Get and Set accessors goes here. 以下代碼示例闡釋提供其名稱與類型相同的屬性。VisualBasic

28、Public Enum Color Insert code for Enum here. End EnumPublic Class Control Public Property Color As Color Get Insert code here. End Get Set Insert code here. End Set End PropertyEnd ClassC#public enum Color / Insert code for Enum here.public class Control public Color Color get / Insert code here. se

29、t / Insert code here. 以下代碼示例不正確，原因是 Color 屬性是 Integer 類型的。VisualBasicPublic Enum Color Insert code for Enum here. End EnumPublic Class Control Public Property Color As Integer Get Insert code here. End Get Set Insert code here. End Set End PropertyEnd ClassC#public enum Color / Insert code for Enum

30、here.public class Control public int Color get / Insert code here. set / Insert code here. 在不正確的示例中，不可能引用 Color 枚舉的成員。Color.Xxx 將被解釋為訪問一個(gè)成員，該成員首先獲取 Color 屬性（在 Visual Basic 中為 Integer 類型，在 C# 中為 int 類型）的值，然后再訪問該值的某個(gè)成員（該成員必須是 System.Int32 的實(shí)例成員）。1.1.15事件命名指南以下規(guī)則概述事件的命名指南： 使用 Pascal 大小寫。 不要使用匈牙利語(yǔ)表示法。 對(duì)

31、事件處理程序名稱使用 EventHandler 后綴。 指定兩個(gè)名為 sender 和 e 的參數(shù)。sender 參數(shù)表示引發(fā)事件的對(duì)象。sender 參數(shù)始終是 object 類型的，即使在可以使用更為特定的類型時(shí)也如此。與事件相關(guān)聯(lián)的狀態(tài)封裝在名為 e 的事件類的實(shí)例中。對(duì) e 參數(shù)類型使用適當(dāng)而特定的事件類。 用 EventArgs 后綴命名事件參數(shù)類。 考慮用動(dòng)詞命名事件。例如，命名正確的事件名稱包括 Clicked、Painting 和 DroppedDown。 使用動(dòng)名詞（動(dòng)詞的“ing”形式）創(chuàng)建表示事件前的概念的事件名稱，用過去式表示事件后。例如，可以取消的 Close 事件應(yīng)

32、當(dāng)具有 Closing 事件和 Closed 事件。不要使用 BeforeXxx/AfterXxx 命名模式。 不要在類型的事件聲明上使用前綴或者后綴。例如，使用 Close，而不要使用 OnClose。 通常情況下，對(duì)于可以在派生類中重寫的事件，應(yīng)在類型上提供一個(gè)受保護(hù)的方法（稱為 OnXxx）。此方法只應(yīng)具有事件參數(shù) e，因?yàn)榘l(fā)送方總是類型的實(shí)例。 以下示例闡釋具有適當(dāng)名稱和參數(shù)的事件處理程序。VisualBasicPublic Delegate Sub MouseEventHandler(sender As Object, e As MouseEventArgs)C#public del

33、egate void MouseEventHandler(object sender, MouseEventArgs e);以下示例闡釋正確命名的事件參數(shù)類。VisualBasicPublic Class MouseEventArgs Inherits EventArgs Dim x As Integer Dim y As Integer Public Sub New MouseEventArgs(x As Integer, y As Integer) me.x = x me.y = y End Sub Public Property X As Integer Get Return x End

34、 Get End Property Public Property Y As Integer Get Return y End Get End PropertyEnd ClassC#public class MouseEventArgs : EventArgs int x; int y; public MouseEventArgs(int x, int y) this.x = x; this.y = y; public int X get return x; public int Y get return y; 1.2 ORACLE命名規(guī)則l 在命名表時(shí)，使用全大寫名稱；連接的單詞間用“_”隔

35、開。例如，MATERIAL_BALANCEl 用單數(shù)形式表示名稱。例如，使用 EMPLOYEE，而不是 EMPLOYEES。 l 在命名表的列時(shí)，一般不要重復(fù)表的名稱；例如，在名為 EMPLOYEE的表中避免使用名為 EMPLOYEE_BIRTHDAY的字段，但為ID和NAME的字段可使用表名為前綴。 l 不要在列的名稱中包含數(shù)據(jù)類型。如果后來(lái)有必要更改數(shù)據(jù)類型，這將減少工作量。 將每個(gè)主要的 SQL 子句放在不同的行上，這樣更容易閱讀和編輯語(yǔ)句，例如： SELECT first_name, last_nameFROM customersWHERE state = WA2 注釋軟件文檔以兩種形

36、式存在：外部的和內(nèi)部的。外部文檔（如規(guī)范、幫助文件和設(shè)計(jì)文檔）在源代碼的外部維護(hù)。內(nèi)部文檔由開發(fā)人員在開發(fā)時(shí)在源代碼中編寫的注釋組成。不考慮外部文檔的可用性，由于硬拷貝文檔可能會(huì)放錯(cuò)地方，源代碼清單應(yīng)該能夠獨(dú)立存在。外部文檔應(yīng)該由規(guī)范、設(shè)計(jì)文檔、更改請(qǐng)求、錯(cuò)誤歷史記錄和使用的編碼標(biāo)準(zhǔn)組成。內(nèi)部軟件文檔的一個(gè)難題是確保注釋的維護(hù)與更新與源代碼同時(shí)進(jìn)行。盡管正確注釋源代碼在運(yùn)行時(shí)沒有任何用途，但這對(duì)于必須維護(hù)特別復(fù)雜或麻煩的軟件片段的開發(fā)人員來(lái)說(shuō)卻是無(wú)價(jià)的。以下幾點(diǎn)是推薦的注釋方法： l 如果用 C# 進(jìn)行開發(fā)，請(qǐng)使用 XML 文檔功能。有關(guān)更多信息，請(qǐng)參見：XML 文檔。 l 修改代碼時(shí)，總是使

37、代碼周圍的注釋保持最新。 l 在每個(gè)例程的開始，提供標(biāo)準(zhǔn)的注釋樣本以指示例程的用途、假設(shè)和限制很有幫助。注釋樣本應(yīng)該是解釋它為什么存在和可以做什么的簡(jiǎn)短介紹。 l 避免在代碼行的末尾添加注釋；行尾注釋使代碼更難閱讀。不過在批注變量聲明時(shí)，行尾注釋是合適的；在這種情況下，將所有行尾注釋在公共制表位處對(duì)齊。 l 避免雜亂的注釋，如一整行星號(hào)。而是應(yīng)該使用空白將注釋同代碼分開。 l 避免在塊注釋的周圍加上印刷框。這樣看起來(lái)可能很漂亮，但是難于維護(hù)。 l 在部署之前，移除所有臨時(shí)或無(wú)關(guān)的注釋，以避免在日后的維護(hù)工作中產(chǎn)生混亂。 l 如果需要用注釋來(lái)解釋復(fù)雜的代碼節(jié)，請(qǐng)檢查此代碼以確定是否應(yīng)該重寫它。盡

38、一切可能不注釋難以理解的代碼，而應(yīng)該重寫它。盡管一般不應(yīng)該為了使代碼更簡(jiǎn)單以便于人們使用而犧牲性能，但必須保持性能和可維護(hù)性之間的平衡。 l 在編寫注釋時(shí)使用完整的句子。注釋應(yīng)該闡明代碼，而不應(yīng)該增加多義性。 l 在編寫代碼時(shí)就注釋，因?yàn)橐院蠛芸赡軟]有時(shí)間這樣做。另外，如果有機(jī)會(huì)復(fù)查已編寫的代碼，在今天看來(lái)很明顯的東西六周以后或許就不明顯了。 l 注釋代碼中不十分明顯的任何內(nèi)容。 l 為了防止問題反復(fù)出現(xiàn)，對(duì)錯(cuò)誤修復(fù)和解決方法代碼總是使用注釋，尤其是在團(tuán)隊(duì)環(huán)境中。 l 對(duì)由循環(huán)和邏輯分支組成的代碼使用注釋。這些是幫助源代碼讀者的主要方面。 l 在整個(gè)應(yīng)用程序中，使用具有一致的標(biāo)點(diǎn)和結(jié)構(gòu)的統(tǒng)一樣

39、式來(lái)構(gòu)造注釋。 l 用空白將注釋同注釋分隔符分開。在沒有顏色提示的情況下查看注釋時(shí)，這樣做會(huì)使注釋很明顯且容易被找到。2.1 XML文檔在 Visual C# 中，可以將使用 XML 編寫的代碼文檔化。C# 是 Visual Studio.NET 中唯一具有此項(xiàng)功能的編程語(yǔ)言。請(qǐng)?jiān)诖a構(gòu)造（如類型和類型成員）上處理標(biāo)記。注意不在命名空間上處理標(biāo)記。編譯器將處理任何為有效 XML 的標(biāo)記。下列標(biāo)記提供了用戶文檔中常用的功能：11111112.1.1 描述標(biāo)記語(yǔ)法:description其中:description 對(duì)象的摘要。 備注 標(biāo)記應(yīng)當(dāng)用于描述類型或類型成員。使用 添加針對(duì)某個(gè)類型說(shuō)明的補(bǔ)

40、充信息。有關(guān) 標(biāo)記的文本是關(guān)于智能感知中類型信息的唯一來(lái)源，并且也顯示在對(duì)象瀏覽器和代碼注釋 Web 報(bào)表中。示例/ xml_summary_tag.cs/ compile with: /doc:xml_summary_tag.xml/ text for class MyClasspublic class MyClass / MyMethod is a method in the MyClass class. / Heres how you could make a second paragraph in a description. for information about output

41、statements. / / public static void MyMethod(int Int1) / text for Main public static void Main () 2.1.2 詳述標(biāo)記 語(yǔ)法description其中description 成員的說(shuō)明。 備注 標(biāo)記用于添加有關(guān)某個(gè)類型的信息，從而補(bǔ)充由 所指定的信息。此信息將顯示在對(duì)象瀏覽器和代碼注釋 Web 報(bào)表中。示例/ xml_remarks_tag.cs/ compile with: /doc:xml_remarks_tag.xml / / You may have some primary informa

42、tion about this class./ / / You may have some additional information about this class./ public class MyClass / text for Main public static void Main () 2.1.3 參數(shù)說(shuō)明 語(yǔ)法description其中 name 方法參數(shù)名。將此名稱用單引號(hào)括起來(lái) ( )。 description 參數(shù)說(shuō)明。 備注 標(biāo)記應(yīng)當(dāng)用于方法聲明的注釋中，以描述方法的一個(gè)參數(shù)。有關(guān) 標(biāo)記的文本將顯示在智能感知、對(duì)象瀏覽器和代碼注釋 Web 報(bào)表中。示例/ xml_pa

43、ram_tag.cs/ compile with: /doc:xml_param_tag.xml / text for class MyClasspublic class MyClass / Used to indicate status. public static void MyMethod(int Int1) / text for Main public static void Main () 2.1.4 返回說(shuō)明 語(yǔ)法description其中description 返回值的說(shuō)明。 備注 標(biāo)記應(yīng)當(dāng)用于方法聲明的注釋，以描述返回值。示例/ xml_returns_tag.cs/ comp

44、ile with: /doc:xml_returns_tag.xml / text for class MyClasspublic class MyClass / Returns zero. public static int GetZero() return 0; / text for Main public static void Main () 2.1.5 舉例標(biāo)記 語(yǔ)法description其中description 代碼示例的說(shuō)明。 備注使用 標(biāo)記可以指定使用方法或其他庫(kù)成員的示例。一般情況下，這將涉及到 標(biāo)記的使用。示例/ xml_example_tag.cs/ compile w

45、ith: /doc:xml_ctag.xml/ text for class MyClasspublic class MyClass / / The GetZero method. / / This sample shows how to call the GetZero method. / / class MyClass / / public static int Main() / / return GetZero(); / / / / public static int GetZero() return 0; / text for Main public static void Main

46、() 2.1.6 異常說(shuō)明 語(yǔ)法description其中cref = member 對(duì)可從當(dāng)前編譯環(huán)境中獲取的異常的引用。編譯器檢查到給定異常存在后，將 member 轉(zhuǎn)換為輸出 XML 中的規(guī)范化元素名。必須將 member 括在雙引號(hào) ( ) 中。 description 說(shuō)明。 備注 標(biāo)記使您可以指定哪些異?？杀灰l(fā)。該標(biāo)記應(yīng)用于方法定義。使用 /doc 進(jìn)行編譯可以將文檔注釋處理到文件中。示例/ xml_exception_tag.cs/ compile with: /doc:xml_exception_tag.xmlusing System;/ comment for classp

47、ublic class EClass : Exception / class definition ./ Thrown when. .class TestClass public static void Main() try catch(EClass) 2.1.7 屬性說(shuō)明語(yǔ)法property-description其中property-description 屬性的說(shuō)明。 備注 標(biāo)記使您得以描述屬性。請(qǐng)注意，當(dāng)在 Visual Studio .NET 開發(fā)環(huán)境中通過代碼向?qū)砑訉傩詴r(shí)，它將會(huì)為新屬性添加 標(biāo)記。然后，應(yīng)該手動(dòng)添加 標(biāo)記以描述該屬性所表示的值。示例/ xml_value_tag.cs/ compile with: /doc:xml_value_tag.xmlusing System;/ text for class Employeepublic class Employee private string name; / Name accesses the value of the name data member public string Name get return name; set name = value; / text for class MainClasspublic cla