搜索
AllrightsreservedPage1,Total133.NET编码规范(仅限内部研发人员）作者:审阅:批准:部门:平台组部门:部门:姓名:姓名:姓名:日期:2008-9-16日期:日期:以下人员协助完成此文档：附录A文档注释第2页共133页变更历史日期版本作者更改说明参考2008-9-16建立附录A文档注释第3页共133页目录附录A文档注释第4页共133页Keywords关键词：Abstract摘要：Listofabbreviations缩略语清单：对本文所用缩略语进行说明，要求提供每个缩略语的英文全名和中文解释。Describeabbreviationsinthisdocument,fullspellingoftheabbreviationandChineseexplanationshouldbeprovided.Abbreviations缩略语Fullspelling英文全名Chineseexplanation中文解释附录A文档注释第5页共133页1简介1.1目的本文档面向.NET开发人员，说明.NET设计与开发是需要遵守的约定、惯用法与模式。这些准则用于帮助.NET设计人员理解如何在不同解决方案之间进行权衡。在特殊情况下，要实现好的库设计，可能会需要违反这些设计准则。这类情况应该很少见，所以必须有充分的理由才能作出这种“违反”决定。部分版权所有2005MicrosoftCorporation。部分版权所有Addison-WesleyCorporation。1.2范围主要包含各.NET开发项目都必须遵循的命名准则、类型设计指南、成员设计指南、扩展性设计、异常设计与使用指南。2命名准则对于组成类库的元素（包括程序集、命名空间、类型、成员和参数），命名准则提供如何为这些元素选择合适的标识符的准则。选择符合这些准则的标识符可以提高您的库的可用性，并使用户相信您的库将不需要学习一组新的规则。为了提供一致的开发人员体验，公共公开的元素（如公共类和受保护的方法）必须遵守这些准则。然而，为在整个代码中保持一致性以及改进可维护性，应考虑在整个代码中始终使用这些约定。2.1大小写约定许多命名约定都与标识符的大小写有关。值得注意的是，公共语言运行库(CLR)支持区分大小写和不区分大小写的语言。本主题中描述的大小写约定可帮助开发人员理解和使用库。附录A文档注释第6页共133页2.1.1大小写样式下列术语描述了标识符的不同大小写形式。2.1.1.1Pascal大小写将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal大小写。例如：BackColor2.1.1.2大小写混合标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColor2.1.1.3大写标识符中的所有字母都大写。例如：IO2.1.2标识符的大小写规则如果标识符由多个单词组成，请不要在各单词之间使用分隔符，如下划线（“_”）或连字符（“-”）等。而应使用大小写来指示每个单词的开头。下列准则是用于标识符的通用规则。2.1.2.1对于由多个单词组成的所有公共成员、类型及命名空间名称，要使用Pascal大小写。注意，这条规则不适用于实例字段。由于成员设计指南中详细说明的原因，不应使用公共实例字段。2.1.2.2对参数名称使用大小写混合。下表汇总了标识符的大小写规则，并提供了不同类型标识符的示例。标识符大小写方式示例类PascalAppDomain枚举类型PascalErrorLevel枚举值PascalFatalError附录A文档注释第7页共133页事件PascalValueChanged异常类PascalWebException只读的静态字段PascalRedValue接口PascalIDisposable方法PascalToString命名空间PascalSystem.Drawing参数CameltypeName属性PascalBackColor2.1.3首字母缩写词的大小写规则首字母缩写词是由术语或短语中各单词的首字母构成的单词。例如，HTML是HypertextMarkupLanguage的首字母缩写。只有在公众广为认知和理解的情况下，才应在标识符中使用首字母缩写词。首字母缩写词不同于缩写词，因为缩写词是一个单词的缩写。例如，ID是identifier的缩写。通常情况下，库名不应使用缩写词。注意可在标识符中使用的两个缩写词是ID和OK。在采用Pascal大小写格式的标识符中，这两个缩写词的大小写形式应分别为Id和Ok。如果在采用大小写混合格式的标识符中将这两个缩写词用作首个单词，则它们的大小写形式应分别为id和ok。首字母缩写词的大小写取决于首字母缩写词的长度。所有首字母缩写词应至少包含两个字符。为了便于这些准则的实施，如果某一首字母缩写词恰好包含两个字符，则将其视为短型首字母缩写词。包含三个或三个以上字符的首字母缩写词为长型首字母缩写词。下列准则为短型和长型首字母缩写词指定了正确的大小写规则。标识符大小写规则优先于首字母缩写词大小写规则。2.1.3.1两字符首字母缩写词的两个字符都要大写，但当首字母缩写词作为大小写混合格式的标识符的首个单词时例外。例如，名为DBRate的属性是一个采用Pascal大小写格式的标识符，它使用短型首字母缩写词(DB)作为首个单词。又如，名为ioChannel的参数是一个采用大小写混合格式的标识符，它使用短型首字母缩写词(IO)作为首个单词。附录A文档注释第8页共133页2.1.3.2包含三个或三个以上字符的首字母缩写词只有第一个字符大写，但当首字母缩写词作为大小写混合格式的标识符的首个单词时例外。例如，名为XmlWriter的类是一个采用Pascal大小写格式的标识符，它使用长型首字母缩写词作为首个单词。又如，名为htmlReader的参数是一个采用大小写混合格式的标识符，它使用长型首字母缩写词作为首个单词。2.1.3.3如果任何首字母缩写词位于采用大小写混合格式的标识符开头，则无论该首字母缩写词的长度如何，都不大写其中的任何字符。例如，名为xmlStream的参数是一个采用大小写混合格式的标识符，它使用长型首字母缩写词(xml)作为首个单词。又如，名为dbServerName的参数是一个采用大小写混合格式的标识符，它使用短型首字母缩写词(db)作为首个单词。2.1.4复合词和常用术语的大小写规则2.1.4.1不要将所谓的紧凑格式复合词中的每个单词都大写。这种复合词是指写作一个单词的复合词，如“endpoint”。例如，hashtable是一个紧凑格式的复合词，应将其视为一个单词并相应地确定大小写。如果采用Pascal大小写格式，则该复合词为Hashtable；如果采用大小写混合格式，则该复合词为hashtable。若要确定某个单词是否是紧凑格式的复合词，请查阅最新的词典。下表列出了不是紧凑格式复合词的一些常用术语。术语先以Pascal大小写格式显示，后面的括号中的是其大小写混合格式。BitFlag(bitFlag)FileName(fileName)LogOff(logOff)LogOn(logOn)SignIn(signIn)SignOut(signOut)UserName(userName)WhiteSpace(whiteSpace)2.1.5区分大小写大小写准则只是为了使标识符更易于阅读和辨认。不能将大小写规则用作避免库元素之间的命名冲突的手段。2.1.5.1不要假定所有编程语言都区分大小写。事实并非如此。不能仅凭大小写区分名称。2.2通用命名约定通用命名约定讨论的是如何为库元素选择最适当的名称。这些准则适用于所有标识符。后面各节讨论特定元素（如命名空间或属性）的命名。附录A文档注释第9页共133页2.2.1选择名称2.2.1.1请选择易读的标识符名称。例如，英文属性名称HorizontalAlignment比AlignmentHorizontal更具可读性。2.2.1.2可读性比简洁性更重要。属性名称CanScrollHorizontally比ScrollableX（指X轴，但意义不明确）更好。2.2.1.3不要使用下划线、连字符或任何其他非字母数字字符。2.2.1.4不要使用匈牙利表示法。匈牙利表示法是在标识符中使用一个前缀对参数的某些元数据进行编码，如标识符的数据类型。2.2.1.5避免使用与常用编程语言的关键字冲突的标识符。虽然符合CLS的语言必须提供将关键字用作普通字的方法，最佳做法不要求强制开发人员了解如何实现。对于大多数编程语言，语言参考文档都会提供语言所使用的关键字列表。下表提供了某些常用编程语言的参考文档的链接。语言链接C#C#参考C++C++LanguageReferenceVisualBasicVisualBasic参考2.2.2缩写和首字母缩写词通常，不应使用缩写或首字母缩写词。这类名称的可读性较差。同样，要确定某个首字母缩写词是否已受到广泛认可也是很困难的。有关缩写的大写规则，请参见首字母缩写词的大小写规则。2.2.2.1不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用OnButtonClick而不要使用OnBtnClick。附录A文档注释第10页共133页2.2.2.2除非必要，不要使用任何未被广泛接受的首字母缩写词。2.2.3语言特定的名称2.2.3.1对于类型名称，应使用语义上有意义的名称而不要使用语言特定的关键字。例如，名称GetLength比GetInt更好。2.2.3.2在标识符的语义含义仅限于其类型的极少数情况下，应使用一般公共语言运行库(CLR)类型名称，而不要使用语言特定的名称。例如，将数据转换为Int16的方法应命名为ToInt16而不是ToShort，因为Short是Int16的语言特定的类型名称。下表显示的是公共编程语言和CLR的相应语言特定的类型名称。C#类型名称VisualBasic类型名称JScript类型名称VisualC++类型名称Ilasm.exe表示形式CLR类型名称sbyteSBytesBytecharint8SBytebyteBytebyteunsignedcharunsignedint8ByteshortShortshortshortint16Int16ushortUInt16ushortunsignedshortunsignedint16UInt16intIntegerintintint32Int32uintUInt32uintunsignedintunsignedint32UInt32longLonglong__int64int64Int64ulongUInt64ulongunsigned__int64unsignedint64UInt64floatSinglefloatfloatfloat32SingledoubleDoubledoubledoublefloat64DoubleboolBooleanbooleanboolboolBooleancharCharcharwchar_tcharChar附录A文档注释第11页共133页stringStringstringStringstringStringobjectObjectobjectObjectobjectObject2.2.3.3在标识符没有语义含义且参数的类型不重要的极少数情况下，应使用通用名称（如值或项），而不要重复类型名称。2.3程序集和DLL的名称大多数情况下，程序集包含全部或部分可重用库，且它包含在单个动态链接库(DLL)中。一个程序集可拆分到多个DLL中，但这非常少见，在此准则中也没有说明。程序集和DLL是库的物理组织，而命名空间是逻辑组织，其构成应与程序集的组织无关。命名空间可以且经常跨越多个程序集。2.3.1.1一定要为程序集DLL选择指示大的功能块（如System.Data）的名称。程序集和DLL的名称不必对应于命名空间名称，但是在命名程序集时遵循命名空间名称这种做法是合理的。2.3