《.NET设计规范》——学习笔记(3) 命名规范

一组一致的的命名约定对框架的可用性及其重要。 名字要易于理解，同时必须传达每个元素的功能。

大小写约定

标识符的大小写规则

PascalCasing：如HtmlTag  IOStream

camelCasing：如htmlTag  ioStream

• 要把PascalCasing用于由多个单词构成的名字空间、类型、以及成员的名字；
• 要把camelCasing用于参数的名字。

通用命名约定

单词的选择

对框架中标识符的名字来说，很重要的一点是一目了然。

名字的意思清楚比长度短更重要。名字应该与场景、系统的逻辑组成或物理组成以及为人熟知的概念相对应，而不应该与技术或框架相对应。

• 要为标识符选择易于阅读的名字；
• 要更看重可读性，而不是更看重简短性；
• 不要使用下划线、连字符以及其他任何既非字母也非数字的字符；
• 不要使用匈牙利命名法；
• 避免使用与广泛使用的编程语言的关键字有冲突的标识符。

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

一般来说，不要在标识符中使用单词缩写或首字母缩写：宁可名字长一点，也不要别人看不懂。  尤其不要使用未被广泛接受的单词缩写和首字母缩写词。

• 不要使用缩写词或缩略词作为标识符名字的一部分
  用GetWindow  不用GetWin
• 不要使用未被广泛接受的首字母缩写词
  多谓广泛接受：用搜索引擎在网上搜索该首字母缩写词，如果返回的前几个结果与期望相符，那么该首字母缩写词才有资格被称为众所周知。

避免使用语言特有的名字

• 要给类型名使用语义上有意义的名字，而不要使用特有的关键字
  GetLength比GetInt要好
• 要使用CLR的通用类型名，而不要使用语言特有的别名
• 要使用常见的名字，比如value或item，而不要重复类型的名字

为已有API的新版本命名

当用新类型和新成员接替或取代已有的类型或成员时，如何选择名字：

• 使用与旧API相似的名字
• 要优先使用后缀而不是前缀来表示已有API的新版本
  这样有助于在浏览文档或使用Intellisense时发现新版本：按字母排序
• 可以考虑使用全新但有意义的标识符
• 要使用数字后缀来表示已有API的新版本
  有些名字（或工业标准）不宜添加后缀或改名
• 不要在标识符中使用“Ex”“New”等类似的后缀来区分相同API的不同版本
• 要在引入64位整数（long）而非32位整数进行操作的新版本API时使用“64”后缀，反之亦然。

程序集和DLL的命名

程序集是一个部署单元，同时还代表托管代码程序的身份。虽然程序集可以分布一个或多个文件中，但一般来说一个程序集仅与一个DLL相对应。

名字空间与DLL程序集的区别：

名字空间：一组逻辑实体

DLL和程序集：打包和部署时的一个单

• 要为程序集和DLL选择提示性的名字，比如System.Data，这样很容易就知道它的大致功能。
• DLL命名：<Company>.<Component>.dll

名字空间的命名

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

• 要用公司名称作为名字空间的前缀，不要用缩写
• 要用稳定的与版本无关的产品名称作为名字空间的第二层
• 不要根据公司的组织架构来决定名字空间的层次结构，因为公司内部组织的名称一般来说不会持续太长的时间
• 要使用PascalCasing大小写风格，并用点号来分隔名字空间的各部分。
  如Microsoft.Office.PowerPoint
• 考虑适当的时候在名字空间中使用复数形式。  首字母缩写词例外
  System.Collections
  System.IO
• 不要用相同的名字来命名名字空间与位于该名字空间中的类型
  如：不要将名字空间命名为Debug，然后又在该名字空间中提供一个名为Debug的类。

名字空间和类型冲突

• 不要引入太一般化的类型名，比如Element、Node、Log以及Message。

不同类型的名字空间，有不同的规范来避免类型名的冲突：

• 应用程序模型名字空间（application model namespace）
  属于单个应用程序模型的名字空间经常一起使用，但是它们几乎不合属于其他应用程序模型的名字空间一起使用
  System.Windows*
  System.UI*
• 基础设施名字空间（infrastructure namespace）
  此类别包含一些在开发常用应用程序时很少会导入的名字空间
• 核心名字空间（core namespace）
  包含了所有的System名字空间，但应用程序模块名字空间和基础设施名字空间除外。  包括System、System.IO、System.Xml以及System.Net等等
• 技术名字空间组（technology namespace group）
  此类别包含所有那些以相同的两个前缀（<Company>.<Technology>*）开始的名字空间。

类、结构和接口的命名

一般来说类型名应该是名词词组。如果无法为类型找到一个名词词组，那么应该重新考虑类型的总体设计。

另一个中重要的考虑因素：最易于识别的名字应该用于最常用的类型。

最常用的类型名应该反映出使用场景，而不是继承层次。

• 要用名词词组来给类型命名。使用PascalCasing风格
• 不要给类名加前缀
  只有接口才能（可以）被加前缀“I”，那是因为.NET框架受到COM及Java的影响
• 考虑让派生类的名字以其基类结尾
  public class FileStream : Stream {...}
• 要确保一对类/接口的名字只差一个“I”前缀，如果该类是该接口的标准实现。
  public interface IComponent {...}
  public class Component : IComponent {...}

泛型类型参数的命名

• 要用描述性的名字来命名
• 考虑用T来命名参数类型
• 要给描述性的类型参数名加上T前缀
• 考虑在类型参数中显示出施加于该类型参数上的限制

枚举类型的命名

• 要用单数名词来命名枚举类型，除非它表示的是位域（bit field）
• 不要给枚举类型的名字添加“Enum”后缀，也不要添加“Flag”、“Flags”等后缀
• 不要给枚举类型值的名字添加前缀
  此规范与C++中通常所使用的恰好相反。在C++中给枚举的每个成员加上完成的限定符是很重要的，因为它们可能在枚举名的作用域之外被访问。但是在托管代码中，枚举成员只能通过枚举名的作用域来访问。

类型成员的命名

类型：方法、属性、事件、构造函数、字段

方法的命名

要尽量根据方法所对应的任务来给它们命名，而不要根据一些实现细节。

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

属性的命名

• 要用名词、名词词组或形容词来命名属性
• 不要让属性名看起来与“Get”方法的名字相似
• 要用肯定性的短语（CanSeek而不是CantSeek）来命名布尔属性
• 考虑用属性的类型名来命名属性
  public enum Color {...}
  public class Control
  {
      public Color Color
      {
          get {...}
          set {...}
      }
  }

事件的命名

• 要用动词或动词短语来命名事件
  事件总是表示一些动作，要么正在发生，要么已经发生
• 要用现在时和过去时来赋予事件名之前和之后的概念
  窗口关闭之前发生的close事件：Closing
  窗口关闭之后发生的close时间：Closed
• 不要用Before和After前缀或后缀来区分前置和后置事件
• 要在命名事件处理函数（用作事件类型的委托）时加上“EventHandler”后缀
• 要在事件处理函数中用sender和e作为两个参数的名字
  sender：触发事件的对象，在整个.NET框架中，sender为object类型
• 要在命名事件的参数类型时加上“EventArgs”后缀

字段的命名

• PascalCasing风格
• 名词或名词短语
• 不要给字段名添加前缀

参数的命名

• camelCasing风格
• 要使用描述性的参数名
  参数名要具备足够的描述性，使得在大多数情况下，用户根据参数的名字和类型就能够确定它的意思
• 考虑根据参数的意思而不是参数的类型来命名参数

资源的命名

本地化的资源就好比是属性，可以通过特定的对象来引用。因此，它的命名规范与属性的相似。

• 要在命名属性关键字（resource key）时使用PascalCasing大小写风格
• 要使标识符的名字具有描述性而不是使名字变短
• 不要使用各主要CLR编程语言特有的关键字
• 要在命名资源时使用字母、数字和下划线
• 要用点号来给标识符清楚地划分层次
• 要在为异常消息资源命名是遵循下面的命名约定：
  资源标识符应该是异常的类型名加一个简短的异常标识符，之间以点号分隔