.NET设计规范————命名规范

NET设计规范：约定、惯用法与模式———命名规范

前言：

         最近在看《.NET设计规范：约定、惯用法与模式》一书，主要仍是讲.NET的设计规范，之前对这一块也不是特别在乎，最近想要把这些系统的学习一下，如下基本上算是读书笔记吧。

第三章命名规范

3.1 大小写约定

使用合适的大小写可使类型、成员以及参数的标识符更容易阅读

3.1.1 标识符大小写原则

为了区分一个标识符中的多个单词，把标识符中的每一个单词的首字母大写，有如下两种合适的方法来大写标识符中的字母，以下：

l  Pascal Casing

l  Camel Casing

PascalCasing约定被用于除了参数名以外的全部标识符，它把标识符中的每一个单词的首字母大写。以下所示：

PropertyDescriptor

Html

两个字母长的首字母缩写词是一个特例，在这种状况下两个字母都要大写，以下所示：

IOStream

Camel Casing约定仅用于参数的名字，它把标识符中除了第一个单词以外的全部单词的首字母都大写。以下所示：

propertyDescriptor

html

ioStream（标识符以两个字母长的的首字母缩写词开始，两个字母都要小写）

标识符基本大小写规范：

要把Pascal Casing用于多个单词构成的名字空间、类型以及成员的名字。

要把Camel Casing用于参数的名字。

不一样类型的标识符的大小写规则以下：

3.1.2 首字母缩写词的大小写

避免在标识符的名字中使用首字母缩写词是很重要的，除非他们很经常使用，可以被使用框架的人马上理解，如：HTML、XML等。

从定义上讲首字母缩写词必须至少有两个字母。由三个或以上的字母组成的首字母缩写词遵循与其余单词同样的规范：只有第一个字母大写，除非是camelCasing风格的参数名中的第一个单词，在这种状况下两个字母都小写。以下所示：

Public void StartIO（Stream ioStream，boolcloseIOStream）

Public void PorcessHtmlTag（string htmlTag）

要把两个字母的首字母缩写词所有大写，除非它是camelCasing风格的参数名的第一个单词

System.IO

Public void StartIO(StreamioStream)

要把由三个或三个以上字母组成的首字母缩写词的第一个字母大写。除非它是camelCasing风格的参数名的第一个单词

System.Xml

Public voidProcessHtmlTag(string htmlTag)

不要把camelCasing 风格的标识符头部的任何首字母缩写词的任何字母大写，不管首字母缩写词的长度是多少

3.1.3 复合词和经常使用术语的大小写

在涉及大小写时，大多数复合词术语要做为单个单词处理。

不要把所谓闭合形式的复合词中每一个单词的首字母大写。

例如：endpoint，为了统一大小写规范，咱们把闭合形式的复合词做为一个单词处理。

经常使用的复合词和经常使用术语的大小写及拼写，以下图所示：

 

上边的示例中有两个经常使用的的其余术语，Ok和Id，它们自己是一个类别，由于它们是俚语性质的经常使用缩写

3.1.4 是否区分大小写

不要觉得全部的编程语言都是区分大小写的，实际状况并不是如此，不该该仅仅经过大小写来区分名字。

3.2 通用命名约定

本章描述一些通用的命名约定，涉及到单词的选择、单词缩写、首字母缩写词的使用规范以及如何避免使用编程语言特有的名字。

3.2.1 单词的选择

对于框架中标识符的名字最重要的一点是一目了然。名字意思清楚比长度短更重要，应该与场景、系统的逻辑组成或物理组成以及为人熟知的概念相对应，不该该与技术活架构相对应。

主要有如下几点：

要为标识符选择易于阅读的名字。

要更看重可读性，而非简短性。

不要使用下划线、连字符以及其余任何既非字母也非数字的字符。

不要使用匈牙利命名法。

避免使用与普遍使用的编程语言的关键字有冲突的标识符。

3.2.2 使用单词缩写和首字母缩写词

不要使用缩写词和缩约词做为标识符名字的一部分。

不要使用未被普遍接受的首字母缩写词（即便是被普遍接受的首字母缩写词，也只应该在必须的时候才使用）

3.2.3 避免使用语言特有的名字

为了确保框架可以充分利用跨语言协做，避免在标识符中使用语言特有的类型名是重要的。

要给类型名使用语义上有意义的名字，而不要使用语言特有的关键字。

要使用CLR的通用类型名，而不要使用语言特有的别名----若是除了类型以外，标识符没有其余的语义。

要使用常见的名字，好比value或item，而不要重复类型的名字----若是除了类型以外，标识符没有其余的语义，并且参数的类型不重要。

3.2.4 为已有API的新版本命名

本节主要描述了当用新类型和新成员接替或取代已有的类型或成员时，如何为它们选择名字。

要在建立已有API的新版本时使用与旧API类似的名字，这有利于突出API之间的关系。

   例如：class AppDommain{}

        Class AppDommainSetup{}

要优先使用后缀而不是前缀来表示已有API的新版本。

考虑使用全新但有意义的标识符，而不是简单的给已有标识符添加后缀或前缀。

要使用数字后缀来表示已有API的新版本—若是已有API的名字时惟一有意义的名字，不宜添加后缀。

例如：publicclass X509Certificate{}

      Public class X509Certificate2{}

不要在标识符中使用“Ex”后缀来区分相同API的不一样版本。

例如：publicclass Car{}

      Public class CarEx{}  //错误的示例

3.3 程序集和DLL的命名

程序集是一个部署单元，同时还表明托管代码程序的身份。通常来讲一个程序集仅与一个DLL相对应。本节主要讲DLL命名约定，程序集的命名约定与此相似。

要记住，名字空间与DLL和程序集是不一样的概念。名字空间对开发人员来讲是一组逻辑实体，而DLL和程序集则是在打包和部署时的一个单元。

要为程序集和DLL选择提示性的名字（例如：System.Data）这样很容易就知道它的大体功能。程序集和DLL的名字不必定要和名字空间相对应，但在程序集命名时遵循名字空间的名字也是合情合理的。

考虑按照以下的模式给DLL命名：

<Company>.<Component>.dll

其中<Component>包含一个或多个以点号分隔的字句，如：

Microsoft.VisualBasic.dll

Microsoft.VisualBasic.Vsa.dll

3.4 名字空间的命名

命名空间的目标是清晰，方便框架的使用者。通常的名字空间命名规则以下：

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

示例以下：

Microsoft.VisualStudio

Microsoft.VisualStudio.Design

Litware.Security

l  要用公司名称做为名字空间的前缀，这样就能够避免与另外一家公司使用相同的名字。

l  要用稳定的、与版本无关的产品名称做为名字空间的第二层。

l  不要根据公司的组织架构来决定名字空间的层次结构，由于公司内部组织的名称通常来讲不会持续太长的时间。

l  要使用PascalCasing大小写风格，并用点号来分隔名字空间中的各部分（例如：Microsoft.office.PowerPoint）.若是商标使用了非传统的大小写风格，那么即便该风格与常规大小写风格相背，也仍是应该遵循商标的大小写风格。

l  考虑在适当的时候在名字空间中使用负数形式。

    例如：要用System.Collections而不要用System.Collection。商标和首字母缩写词除外。

l  不要用相同的名字来命名名字空间与位于该名字空间中的类型。

    例如：不要将名字空间命名为Debug，而后又在该名字空间中提供一个名为Debug的类。

名字空间与类型名的冲突

名字空间用来把类型组织成一个逻辑的、易于浏览的层次结构。对解决在导入多个名字空间时可能引发的类型名的二义性，它们是不可或缺的。

不要引入太通常化的类型名（例如：Element，Node，Log，Message）

    这样的名字很容易引发类型冲突，名字空间能够分为下面的类别：

l  应用程序模型名字空间（application model namespace）

l  基础设施名字空间（infrastructure namespace）

l  核心名字空间（core namespace）

l  技术名字空间组（technology namespace group）

1.      应用程序模型名字空间

不要给位于同一个应用程序模型的名字空间中的类型起相同的名字。

2.      基础设施名字空间

这个类别包含了一些再开发经常使用的应用程序时不多会导入的名字空间。

3.      核心名字空间

核心名字空间包含了全部的System名字空间，但应用程序模型名字空间和基础设置名字空间除外。（核心名字空间包括System、System.IO、System.Xml、System.Net等）

不要给类型会与核心名字空间中的任何类型产生冲突的名字。（例如：不要用Stream来做为类型名，它会和System.IO.Stream产生冲突）

4.      技术名字空间组

这个类别包括全部那些以相同的两个前缀（<Company>.<Technology>*）开始的名字空间（例如：Microsoft.Build.Utilities和Microsoft.Build.Tasks属于同一个技术类型，可是彼此之间不冲突）

不要给类型会与位于同一技术组中的其余类型产生冲突的名字。

不要在技术名字空间和应用程序模型名字空间的类型之间引入类型名冲突（例如：不该给Microsoft.VisualBasic名字空间增长一个Binding类型，由于System.Windows.Forms名字空间已包含该类型名）

3.5 类、结构和接口的命名

通常来说，类型名应该是名词词组，由于他们表明了系统中的实体，若是没法为类型找到一个名词词组，那么可能应该从新考虑该类型的整体设计。

最易识别的名字应该用于最经常使用的类型，最经常使用的类型名应该反映出使用场景，而不是继承层次。大多数用户只是用继承层次的叶节点，而不关心类层次结构。

下面的命名规范适用于通常的类型命名。

要用名词或者名词词组来给类型命名，在极少数状况下也能够用形容词词组来给类型命名。(命名时用PascalCasing大小写风格，这使类型名和方法区分开，后者用动词词组来命名。)

不要给类名加前缀。（惟一的前缀是用于接口“I”）

考虑让派生类的名字以基类的名字结尾。(例如：publicclass FileStream：Stream{…})

要让接口的名字以字母I开头，这样能够显示出该类型是一个接口。（例如：IComponent）

要确保一对类/接口的名字只差一个“I”前缀，若是该类是该接口的标准实现。

     例如： public interface IComponent{…}

            Public class Component :IComponent{…}

3.5.1 泛型类型参数的命名

泛型是.NET框架2.0一个主要特征，它引入了一种称为“类型参数（type parameter）”的新标识符。如下的规范描述了与类型参数有关的命名约定。

要用描述性的名字来命名泛型类型参数，除非一个字母就够了，并且描述性的名字并不能增添什么价值。

    例如：public interface TSessionChannel<TSession>{…}

          Public class List<T>{…}

考虑用T来命名参数类型——若是类型只有一个类型参数，且类型参数只有一个字母。

    例如：public int IComparer<T>{…}

          Public delegate boolPredicate<T>(T item);

要给描述性的类型参数名加上T前缀。

    例如：public interface ISessionChannel<TSession> whereTSession:ISession

{

    TSession Session{get;}

}

考虑在类型参数名中显示出施加于该类型参数上的限制。

3.5.2 经常使用类型的命名

若是要从.NET框架所包含的类型派生新类型，或者要实现.NET框架中的类型，要遵循下表的一个命名规则。以下所示：

3.5.3 枚举类型的命名

通常来讲，枚举类型的命名应该遵循标准的命名规则（PascalCasing 大小写风格）。可是还有一些针对枚举类型的具体规范。

要用单数名词来命名枚举类型，除非它表示的事位域（bit field）

要用复数名词来命名表示位域的枚举类型，这样的枚举类型也称为标记枚举（flag enum）

    例如：[Flags]

          Public enum ConsoleModifiers{

          Alt,

          Control,

          Shift

          }

不要给枚举类型的名字添加“Enum”后缀。

    例如： public enum ColorEnum{…}//这样就很差

不要给枚举类型值的名字添加前缀。

    例如：public enum ImageMode{

              ImageModeBitmap=0，

               ImageModeGrayScale=1，

               ImageModeRgb=2

         }

    下边的命名会更好：

          Public enum ImageMode{

               Bitmap=0，

               GrayScale=1，

               Rgb=2

          }

3.6 类型成员的命名

类型由方法、属性、事件、构造函数以及字段等成员组成。

3.6.1 方法的命名

由于方法是用来执行操做的，所以框架的设计规范要求方法名必须是动词或者动词词组。它还用来把方法同属性和类型名区分开，属性和类型名是名词或形容词词组。

要用动词或动词词组来命名方法。

3.6.2 属性的命名

与其余成员不一样，属性应该用名词词组或形容词词组来命名。命名时要始终使用PascalCasing大小写风格。

要用名词、名词词组或形容词来命名属性。

不要让属性名看起来与“Get”方法的名字类似。

要用确定性的短信（CanSeek而不是CantSeek）来命名布尔属性。若是有帮助，还能够有选择性的给布尔值属性添加“Is”，“Can”，“Has”等前缀。

考虑用属性的类型名来命名属性。

    例如：public enum Color{…}

          Public class Control{

              Public Color Color{get{…} set{…}}

          }

3.6.3 事件的命名

事件老是表示一些动做，要么正在发生，要么已经发生。所以和方法同样，要用动词来命名，此外，还要用动词的时态来表示事件发生的时间。

要用动词或动词短语来命名事件。（例如：Clicked，DroppedDown等）

要用如今时和过去时来赋予事件名以以前和以后的概念。

    例如：在窗口关闭以前的close事件命名为Closing，关闭以后的事件命名为Closed

不要用“Before”或“After”前缀或后缀来区分前置和后置事件。

要在命名事件处理函数时加上“EventHandler”后缀。（例如：public delegate void ClickedEventHandler（object sender，ClickedEventArgse）；

要在事件处理函数中用sender 和e做为两个参数的名字。

    参数sender表示触发该事件的对象。

要在命名事件的参数类时加上“EventArgs”后缀。

3.6.4 字段的命名

    字段的命名规范适用于静态共有字段和静态受保护字段。

    要在命名字段时使用PascalCasing大小写风格。

    要用名词或名词短语来命名字段。

不要给字段名添加前缀。（例如：不要用“g_”或”s_”来区分静态和非静态字段）

3.7 参数的命名

要在命名参数时使用camelCasing大小写风格。

要使用具备描述性的参数名。

    参数名应该具备足够的描述性，在大多数状况下，用户根据参数名字和类型就可以肯定它的意思。

考虑根据参数的意思而不是参数的类型来命名参数。

3.8 资源的命名

本地化的资源就比如是属性，能够经过特定的对象来引用。所以资源的命名规范与属性的命名规范类似。

要在命名资源关键字时使用PascalCasing大小写风格。

要使标识符的名字具备描述性而不是使名字变短。

不要使用各类CLR编程语言特有的关键字。

要在命名资源时仅使用字母、数字和下划线。

要用点号来给标识符清楚的划分层次。

    例如：设计菜单系统资源，命名方式以下：

          Menus.FileMenu.Close.Text

        Menus.FileMenu.Close.Color

要在为异常的消息资源命名时遵循下面的命名约定：

    资源标识符应该是异常的类型名加上一个简短的异常标识符，之间以点号分隔：

    ArgumentException.IllegalCharacters

    ArgumentException.InvalidName