微软推荐的.net命名规范

时间:2023-12-17 21:05:56

许多命名约定都与标识符的大小写有关。值得注意的是,公共语言运行库 (CLR) 支持区分大小写和不区分大小写的语言。本主题中描述的大小写约定可帮助开发人员理解和使用库。

大小写样式

下列术语描述了标识符的不同大小写形式。

Pascal 大小写

将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。例如:

BackColor

大小写混合

标识符的首字母小写,而每个后面连接的单词的首字母都大写。例如:

backColor

大写

标识符中的所有字母都大写。例如:

IO

标识符的大小写规则

如果标识符由多个单词组成,请不要在各单词之间使用分隔符,如下划线(“_”)或连字符(“-”)等。而应使用大小写来指示每个单词的开头。

下列准则是用于标识符的通用规则。

对于由多个单词组成的所有公共成员、类型及命名空间名称,要使用 Pascal 大小写。

注意,这条规则不适用于实例字段。由于成员设计准则中详细说明的原因,不应使用公共实例字段。

对参数名称使用大小写混合。

下表汇总了标识符的大小写规则,并提供了不同类型标识符的示例。

标识符 大小写方式 示例

Pascal

AppDomain

枚举类型

Pascal

ErrorLevel

枚举值

Pascal

FatalError

事件

Pascal

ValueChanged

异常类

Pascal

WebException

只读的静态字段

Pascal

RedValue

接口

Pascal

IDisposable

方法

Pascal

ToString

命名空间

Pascal

System.Drawing

参数

Camel

typeName

属性

Pascal

BackColor

首字母缩写词的大小写规则

首字母缩写词是由术语或短语中各单词的首字母构成的单词。例如,HTML 是 Hypertext Markup Language 的首字母缩写。只有在公众广为认知和理解的情况下,才应在标识符中使用首字母缩写词。首字母缩写词不同于缩写词,因为缩写词是一个单词的缩写。例如,ID 是 identifier 的缩写。通常情况下,库名不应使用缩写词。

可在标识符中使用的两个缩写词是 ID 和 OK。在采用 Pascal 大小写格式的标识符中,这两个缩写词的大小写形式应分别为 Id 和 Ok。如果在采用大小写混合格式的标识符中将这两个缩写词用作首个单词,则它们的大小写形式应分别为 id 和 ok

首字母缩写词的大小写取决于首字母缩写词的长度。所有首字母缩写词应至少包含两个字符。为了便于这些准则的实施,如果某一首字母缩写词恰好包含两个字符,则将其视为短型首字母缩写词。包含三个或三个以上字符的首字母缩写词为长型首字母缩写词。

下列准则为短型和长型首字母缩写词指定了正确的大小写规则。标识符大小写规则优先于首字母缩写词大小写规则。

两字符首字母缩写词的两个字符都要大写,但当首字母缩写词作为大小写混合格式的标识符的首个单词时例外。

例如,名为 DBRate 的属性是一个采用 Pascal 大小写格式的标识符,它使用短型首字母缩写词 (DB) 作为首个单词。又如,名为 ioChannel 的参数是一个采用大小写混合格式的标识符,它使用短型首字母缩写词 (IO) 作为首个单词。

包含三个或三个以上字符的首字母缩写词只有第一个字符大写,但当首字母缩写词作为大小写混合格式的标识符的首个单词时例外。

例如,名为 XmlWriter 的类是一个采用 Pascal 大小写格式的标识符,它使用长型首字母缩写词作为首个单词。又如,名为 htmlReader 的参数是一个采用大小写混合格式的标识符,它使用长型首字母缩写词作为首个单词。

如果任何首字母缩写词位于采用大小写混合格式的标识符开头,则无论该首字母缩写词的长度如何,都不大写其中的任何字符。

例如,名为 xmlStream 的参数是一个采用大小写混合格式的标识符,它使用长型首字母缩写词 (xml) 作为首个单词。又如,名为 dbServerName 的参数是一个采用大小写混合格式的标识符,它使用短型首字母缩写词 (db) 作为首个单词。

复合词和常用术语的大小写规则

不要将所谓的紧凑格式复合词中的每个单词都大写。这种复合词是指写作一个单词的复合词,如“endpoint”。

例如,hashtable 是一个紧凑格式的复合词,应将其视为一个单词并相应地确定大小写。如果采用 Pascal 大小写格式,则该复合词为 Hashtable;如果采用大小写混合格式,则该复合词为 hashtable。若要确定某个单词是否是紧凑格式的复合词,请查阅最新的词典。

通用命名约定

通用命名约定讨论的是如何为库元素选择最适当的名称。这些准则适用于所有标识符。后面各节讨论特定元素(如命名空间或属性)的命名。

选择名称

请选择易读的标识符名称。例如,英文属性名称 HorizontalAlignment 比 AlignmentHorizontal 更具可读性。

可读性比简洁性更重要。属性名称 CanScrollHorizontally 比 ScrollableX(指 X 轴,但意义不明确)更好。

不要使用下划线、连字符或任何其他非字母数字字符。

不要使用匈牙利表示法。

匈牙利表示法是在标识符中使用一个前缀对参数的某些元数据进行编码,如标识符的数据类型。

程序集和 DLL 的名称

大多数情况下,程序集包含全部或部分可重用库,且它包含在单个动态链接库 (DLL) 中。一个程序集可拆分到多个 DLL 中,但这非常少见,在此准则中也没有说明。

程序集和 DLL 是库的物理组织,而命名空间是逻辑组织,其构成应与程序集的组织无关。命名空间可以且经常跨越多个程序集。

一定要为程序集 DLL 选择指示大的功能块(如 System.Data)的名称。程序集和 DLL 的名称不必对应于命名空间名称,但是在命名程序集时遵循命名空间名称这种做法是合理的。

考虑按下面的模式命名 DLL:

<Company>.<Component>.dll

其中 <Component> 包含一个或多个以圆点分隔的子句。

例如,Contoso.WebControls.dll

命名空间的名称

为命名空间选择的名称应指示命名空间中的类型所提供的功能。例如,System.Net.Sockets 命名空间包含的类型允许开发人员使用套接字通过网络进行通信。

命名空间名称的一般格式如下:

<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]

例如,Microsoft.WindowsMobile.DirectX

使用公司名称作为命名空间的前缀以防止不同公司开发的命名空间具有相同的名称和前缀。

在命名空间名称的第二级使用稳定的、与版本无关的产品名称。

不要根据组织层次结构确定命名空间层次结构中的名称,因为公司的部门名称经过一段时间后可能会改变。

命名空间名称是长期使用的、不会更改的标识符。组织的不断发展和变化不应使命名空间名称过时。

使用 Pascal 大小写格式,并用句点分隔命名空间各部分(如 Microsoft.Office.PowerPoint)。如果您的品牌采用了非传统的大小写,应遵循您的品牌所定义的大小写,即使它与常用的命名空间大小写相背离也如是。

适当的时候可考虑使用复数命名空间名称。例如,使用 System.Collections 而不使用 System.Collection。但是,品牌名称和首字母缩写词属于此规则的例外情况。例如,使用 System.IO,而不要使用 System.IOs。

命名空间和其中的类型不要使用相同的名称。例如,不要在将“Debug”用作命名空间名称的同时,又在该命名空间中提供一个名为“Debug”的类。有些编译器要求对这种类型进行完全限定。

命名空间和类型的名称冲突

如果选择的命名空间或类型的名称与现有名称冲突,则库的用户将不得不对受影响的项的引用进行限定。在大多数开发情况中,都不应出现这种问题。

本节提供的某些准则适用于下面的命名空间类别:

  • 应用程序模型命名空间

  • 基础结构命名空间

  • 核心命名空间

  • 技术命名空间组

应用程序模型中的命名空间提供特定于应用程序中的某个类的功能集。例如,System.Windows.Forms 命名空间中的类型提供编写 Windows 窗体客户端应用程序所需的功能。System.Web 命名空间中的类型支持编写基于 Web 的服务器应用程序。通常,在同一应用程序中不会使用不同应用程序模型中的命名空间,因此,这降低了名称冲突影响使用您的库的开发人员的可能性。

基础结构应用程序提供专门的支持,很少在程序代码中进行引用。例如,程序开发工具所使用的 *.Designer 命名空间中的类型。*.Permissions 命名空间是基础结构命名空间的另一个示例。与基础结构命名空间中的类型的名称冲突不可能影响使用您的库的开发人员。

核心命名空间是 System.* 命名空间(不包括应用程序命名空间和基础结构命名空间)。System 和 System.Text 都是核心命名空间的示例。应尽可能避免与核心命名空间中的类型发生名称冲突。

属于特定技术的命名空间将具有相同的第一和第二级标识符 (Company.technology.*)。应避免在技术命名空间中出现名称冲突。

命名空间一般准则

不要引入宽泛的类型名称,如 Element、Node、Log 和 Message。在通常情况下,这样极可能导致类型名称冲突。应对宽泛的类型名称进行限定(例如 FormElement、XmlNode EventLog、SoapMessage)。

应用程序命名空间准则

不要在单个应用程序模型内为命名空间中的多个类型指定相同的名称。

例如,如果要编写 Windows 窗体应用程序开发人员要使用的特殊控件库,则不应引入名为 Checkbox 的类型,因为该应用程序模型已存在同名类型 (CheckBox)。

核心命名空间准则

不要指定会与核心命名空间中的任何类型发生冲突的类型名称。

例如,不要使用 Directory 作为类型名称,因为这会与 Directory 类型冲突。

技术命名空间准则

不要分配会与单个技术命名空间内的其他类型发生冲突的类型名称。

不要引入会导致技术命名空间的类型与应用程序模型命名空间中的类型发生冲突的类型名称(除非该技术不用于该应用程序模型)。