C#代码规范.doc

.C# 代码规范1、 前言本文档定义了一些通用的代码规范和准则，一般情况下本文档适用于项目组所有项目，特殊情况下，如果客户有自己的代码规范，以客户的代码优先。2、 大小写约定2.1、 大小写样式，本文中将出现两种大小写样式，这里先分别定义：Pascal大小写将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。例如：BackColorCamel大小写标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColor 匈牙利命名法基本原则是：变量名=属性+类型+对象描述。 例如：lblName2.2、 标识符大小写规则2.2.1、 下表中列出常见的代码元素的样式规范和示例标识符规则示例类PascalAppDomain枚举类型PascalErrorLevel枚举值PascalWarning事件PascalValueChanging, ValueChanged异常类PascalWebException只读的静态字段PascalCurrentUser接口PascalIDisposable方法PascalToString命名空间PascalSystem.Data参数CameltypeName属性PascalName常量全大写MAXLENGTH, LENGTH_MAXWeb或Win控件匈牙利txtName2.2.2、 除了遵循以上大小写约定外还需注意以下约定（除常量为特例）： 如果标识符由多个单词组成，请不要在各单词之间使用分隔符，如下划线（“_”）或连字符（“-”）等。而应使用大小写来指示每个单词的开头。 所有公共的成员如：方法、属性，都应使用Pascal大小写样式2.3、 首缩写词的大小写规则2.3.1、 首字母缩写词首字母缩写词是由术语或短语中各单词的首字母构成的单词。例如，HTML 是 Hypertext Markup Language 的首字母缩写。为了方便编码规范的实施，本文规定受字母缩写词必须至少为两个单词，正好为两个单词的首字母缩写词称其为“短型首字母缩写词”，两个单词以上的称其为“长型首字母缩写词”2.3.2、 单缩写词单缩写词是一个单词的缩写。例如，ID 是 identifier 的缩写。注意：可在标识符中使用的两个缩写词是 ID 和 OK。在采用 Pascal 大小写格式的标识符中，这两个缩写词的大小写形式应分别为 Id 和 Ok。如果在采用大小写混合格式的标识符中将这两个缩写词用作首个单词，则它们的大小写形式应分别为 id 和 ok。2.3.3、 首字母缩写词有以下大小写规则：短型首字母缩写词在Pascal大小写样式中，两个字母都应大写。在Camel大小写样式中，如果是首个单词，两个字母都应小写。例如： 名为 DBRate 的属性是一个采用 Pascal 大小写格式的标识符，它使用短型首字母缩写词 (DB) 作为首个单词。 名为 ioChannel 的参数是一个采用大小写混合格式的标识符，它使用短型首字母缩写词 (IO) 作为首个单词。长型首字母缩写词，在任何大小写样式中都视为一个单词。例如： 名为 XmlWriter 的类是一个采用 Pascal 大小写格式的标识符，它使用长型首字母缩写词作为首个单词。 名为 htmlReader 的参数是一个采用大小写混合格式的标识符，它使用长型首字母缩写词作为首个单词。2.3.4、 复合词的大小写规则：所有复合词在任何大小写样式中都视为一个完整单词。例如，hashtable 是一个紧凑格式的复合词，应将其视为一个单词并相应地确定大小写。如果采用 Pascal 大小写格式，则该复合词为 Hashtable;如果采用大小写混合格式，则该复合词为 hashtable。若要确定某个单词是否是紧凑格式的复合词，请查阅最新的词典。2.3.5、 区分大小写大小写准则只是为了使标识符更易于阅读和辨认。不能将大小写规则用作避免库元素之间的命名冲突的手段。3、 通用命名约定3.1、 通用命名约定讨论的是如何为库元素选择最适当的名称。这些准则适用于所有标识符。后面各节讨论特定元素（如命名空间或属性）的命名。3.2、 名称的选择与命名原则3.2.1、 请选择易读的标识符名称例如，英文属性名称 HorizontalAlignment 比 AlignmentHorizontal 更具可读性。3.2.2、 可读性比简洁性更重要例如，属性名称 CanScrollHorizontally 比 ScrollableX（指 X 轴，但意义不明确）更好。3.2.3、 不要使用下划线、连字符或任何其他非字母数字字符3.2.4、 不要使用匈牙利表示法匈牙利表示法是在标识符中使用一个前缀对参数的某些元数据进行编码，如标识符的数据类型。3.2.5、 避免使用与常用编程语言的关键字冲突的标识符虽然符合 CLS 的语言必须提供将关键字用作普通字的方法，最佳做法不要求强制开发人员了解如何实现。对于大多数编程语言，语言参考文档都会提供语言所使用的关键字列表。3.3、 缩写和首字母缩写单词尽量避免使用缩写或首字母缩写词。这类名称的可读性较差。同样，要确定某个首字母缩写词是否已受到广泛认可也是很困难的。不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用 OnButtonClick 而不要使用 OnBtnClick。除非必要，不要使用任何未被广泛接受的首字母缩写词。3.4、 程序集和DLL的名称所有程序集名称都必须和项目的命名空间相对应。3.5、 命名空间的名称3.5.1、 所有命名空间都需以公司名或产品名为根命名空间。为命名空间选择的名称应指示命名空间中的类型所提供的功能。例如，System.Net.Sockets 命名空间包含的类型允许开发人员使用套接字通过网络进行通信。3.5.2、 命名空间名称的一般格式如下：(|).例如，ClearCost.Repository.Interface。3.5.3、 命名空间和其中的类型不要使用相同的名称。例如，不要在将“Debug”用作命名空间名称的同时，又在该命名空间中提供一个名为“Debug”的类。3.5.4、 命名空间一般准则不要引入宽泛的类型名称，如 Element、Node、Log 和 Message。在通常情况下，这样极可能导致类型名称冲突。应对宽泛的类型名称进行限定（例如 FormElement、XmlNode EventLog、SoapMessage）。3.5.5、 应用程序命名空间准则不要在单个应用程序模型内为命名空间中的多个类型指定相同的名称。例如，如果要编写 Windows 窗体应用程序开发人员要使用的特殊控件库，则不应引入名为 Checkbox 的类型，因为该应用程序模型已存在同名类型。3.5.6、 核心命名空间准则不要指定会与核心命名空间中的任何类型发生冲突的类型名称。例如，不要使用 Directory 作为类型名称，因为这会与 Directory 类型冲突。3.5.7、 技术命名空间准则不要分配会与单个技术命名空间内的其他类型发生冲突的类型名称。不要引入会导致技术命名空间的类型与应用程序模型命名空间中的类型发生冲突的类型名称（除非该技术不用于该应用程序模型）。3.6、 接口、类和结构的名称通常，类型名称应该是名词短语，其中名词是由类型表示的实体。例如，Button、Stack 和 File 都具有名称，用于标识由类型表示的实体。从开发人员的角度选择标识实体的名称;名称应反映使用场合。下面的准则适用于如何选择类型名称： 按照 Pascal 大小写格式，使用名词或名词短语（或偶尔使用形容词短语）为类、接口和值类型命名。 不要为类名加前缀（如字母 C）。接口不适用此规则，它应以字母 I 开头。 考虑在派生类的末尾使用基类名称。例如，从 Stream 继承的 Framework 类型以 Stream 结尾，从 Exception 继承的类型以 Exception 结尾。 为接口名称加上字母 I 前缀，以指示该类型为接口。 在定义类/接口对（其中类是接口的标准实现）时，一定要确保类和接口的名称除接口名称以字母 I 为前缀外，二者应完全相同。例如，Framework 提供 IAsyncResult 接口和 AsyncResult 类。 用描述性名称为泛型类型参数命名，除非单个字母的名称已完全可以自我说明而无需描述性名称。 对具有一个单字母类型参数的类型，考虑将字母 T 用作这些类型的类型参数名称。 将字母 T 作为描述性类型参数名称的前缀。 考虑在参数名称中指示置于类型参数上的约束。例如，约束于 ISession 的参数可称为 TSession。3.7、 常见类型的名称下面的准则提供的命名约定有助于开发人员了解某些类的使用场合： 向自定义属性类添加 Attribute 后缀。 ObsoleteAttribute 和 AttributeUsageAttribute 是符合此准则的类型名称。 向在事件中使用的类型（如 C# 事件的返回类型）的名称添加 EventHandler 后缀。 AssemblyLoadEventHandler 是符合此准则的委托名称。 向不是事件处理程序的委托的名称添加 Callback 后缀。事件处理程序一般以EventHandler结尾 不要向委托添加 Delegate 后缀。 向扩展 System.EventArgs 的类添加 EventArgs 后缀。 不要从 System.Enum 类派生;使用当前所用语言支持的关键字。例如，在 C# 中应使用 enum 关键字。 向从 System.Exception 继承的类型添加 Exception 后缀。 向实现IDictionary 或IDictionary 的类型添加 Dictionary 后缀。注意，System.Collections.IDictionary 是特定类型的集合，但此准则的优先级高于以下更为一般的集合准则。 向实现IEnumerable、ICollection、IList、IEnumerable、ICollection或IList 的类型添加适当的说明性后缀。 向从System.Security.CodeAccessPermission 继承的类型或实现 System.Security.IPermission 的类型添加 Permission 后缀。注意：以上准则中提及的从某个其他类型继承的类型，指的是所有的继承者，而不只是直接继承的类型。例如，“向从 Exception 继承的类型添加 Exception 后缀”这一准则意味着在继承层次结构中具有 Exception 的任何类型都应该使用以 Exception 结尾的名称。每条这样的准则还用来保留指定的后缀; 除非类型满足该准则表述的条件，否则不应使用该后缀。例如，如果类型不是从 Exception 直接或间接继承的，则类型名称不能以 Exception 结尾。3.8、 枚举的名称不要在枚举值名称中使用前缀。例如，不要对 ADO 枚举使用 ad 之类的前缀，也不要对多格式文本枚举使用 rtf 之类的前缀，依此类推。这还意味着不应在枚举值名称中包含枚举类型名称。下面的代码示例演示了不正确的枚举值命名。 正确错误public enum Teams Alpha, Beta, Delta public enum Teams TeamsAlpha, TeamsBeta, TeamsDelta 不要将 Enum 用作枚举类型的后缀。不要在标志枚举的名称中添加 Flags 作为后缀（位域枚举可例外）。对枚举使用单数名称，除非枚举值是位域。对使用位域值的枚举（也称为标志枚举）使用复数名称。3.9、 类型成员的名称类型包含以下几种成员：方法、属性、字段、事件3.9.1、 方法的名称使用动词或动词短语作为方法的名称。通常，方法对数据进行操作，因此，使用动词描述方法的操作可使开发人员更易于了解方法所执行的操作。定义由方法执行的操作时，应从开发人员的角度仔细选择明确的名称。不要选择描述方法如何执行其操作的动词，也就是说，不要使用实现细节作为方法名称。3.9.2、 属性的名称使用名词、名词短语或形容词作为属性的名称。名词短语或形容词适合于属性，因为属性保存数据。不要使用与 Get 方法同名的属性。例如，不要将一个属性命名为 EmployeeRecord，又将一个方法命名为 GetEmployeeRecord。开发人员会不知道使用哪个成员来完成其编程任务。使用肯定性短语作为布尔值属性的名称（如使用 CanSeek 而不使用 CantSeek）。可以为布尔值属性添加前缀（如 Is、Can 或 Has），但要注意使用得当。考虑为属性提供与其类型相同的名称。如果某个属性已强类型化为某个枚举，则该属性可与该枚举同名。例如，如果有一个名为 CacheLevel 的枚举，则返回其中一个枚举值的属性也可以命名为 CacheLevel。 3.9.3、 事件的名称使用动词或动词短语作为事件的名称。在为事件命名时，使用现在时或过去时表示时间上的前后概念。例如，在窗口关闭之前引发的关闭事件可命名为“Closing”，在窗口关闭之后引发的关闭事件可命名为“Closed”。不要使用“Before”或“After”作为前缀或后缀来指示之前和之后发生的事件。使用后缀 EventHandler 命名事件处理程序（用作事件类型的委托）。在事件处理程序签名中使用命名为“sender”和“e”的两个参数。sender 参数的类型应为 Object，e 参数应是 EventArgs 的实例或继承自 EventArgs 的实例。使用 EventArgs 后缀命名事件参数类。3.9.4、 字段的名称字段的命名准则适用于静态公共字段和静态受保护字段。不要定义公共实例字段。在字段名称中使用 Pascal 大小写格式。使用名词或名词短语作为字段的名称。3.10、 参数名称选择适当的参数名称可极大改善库的可用性。适当的参数名称应指示该参数会影响的数据或功能。对参数名称使用 Camel 大小写。使用描述性参数名称。在大多数情况下，参数名称及其类型应足以确定参数的用法。考虑使用反映参数含义的名称而不是反映参数类型的名称。在开发人员工具和文档中，参数的类型通常都是可见的。3.11、 资源的名称本主题中准则适用于可本地化的资源，如错误信息和菜单文本。在资源键中使用 Pascal 大小写格式。提供描述性标识符，而不要提供短标识符。尽量保持标识符的简洁性，但不要牺牲可读性。使用点分隔符（“.”）以清晰的层次结构表示标识符。例如，Menus.FileMenu.Close.Text 和 Menus.FileMenu.Close.Color 等名称符合此准则。对异常消息资源使用下面的命名约定。资源标识符应由异常类型名称加上异常的短标识符构成，二者之间以点分隔。例如，ArgumentException.BadEnumValue 符合此准则。4、 代码规范4.1、 目录结构每个命名空间原则都有单独的文件目录，每个类存储于一个单独的文件中4.2、 换行当一个表达式过长时，可以按照以下原则进行换行 在逗号后换行 在操作符后换行 尽量保持运算模块的完整性 新行应该和上一行在起始处对齐Example of breaking up method calls:longMethodCall(expr1, expr2,expr3, expr4, expr5);Examples of breaking an arithmetic expression:Prefer: Bad:var = a * b / (c - g + f) + var = a * b / (c - g +4 * z; f) + 4 * z;4.3、 缩进应该总是使用TAB进行代码缩进，而不是使用空格4.4、 空行合理使用空行可以增加代码的可读性，使代码逻辑紧疏有序。4.4.1、 在下列情况下，应该使两个空行对代码进行分隔。但就尽量保持每个类一个文件的原则避免。 类与接口的定义之间 类与类的定义之间 类与枚举的定义之间4.4.2、 以下情况，应该使用一个空行对代码进行分隔 两个方法之间 两个属性之间 方法与属性之间 方法内的局部变量定义与逻辑语句之间 方法内的明显的逻辑块之间 备注与其他语句之间（非被备注的语句） Return语句与其它语句之间Perfer: Bad:Public int test() Public int test() int index = 0; int index = 0;doSomething; doSomething; return index; return index; 4.5、 代码格式化4.5.1、 Using语句应该在类的顶端，并进行排序。 （System置顶）4.5.2、 对类内代码进行分组， 推荐顺序如下： 成员变量 构造函数 公共属性 公共方法4.5.3、 对代码进行分组时，同时遵循访问符和可见性原则 Public Protected Internal Private4.5.4、 对某一接口的实现，使用region进行隔离4.5.5、 如果类或方法有多个Attribute时，每个单独占用一行。 Prefer: bad:Attribute1 Attribute1, Attribute2Attribute2 Public Class MyClassPublic Class MyClass 4.6、 注释4.6.1、 使用/或/进行注释， 禁止在正式代码中使用 /*/注释。4.6.2、 除了文件头部，禁止使用类似以下的花式注释/*/Comment block/*4.6.3、 不要用注释去解释显而易见的逻辑， 好的代码应该是自注释的。4.6.4、 如果有必要，可以对复杂逻辑进行描述性注释4.6.5、 推荐文件头部注释格式/ Copyright (C) Accegile/ FileName：CodeStandSample.cs/ File description：/ / Create identifier：klu 2007-02-06/ Modification identifier：klu 2007-02-07/ Modification description：/ Modification identifier：/ Modification description：5、 语言使用最佳实践5.1、 基本原则 显式的定义所有成员的访问符。Prefer: Bad:public void WriteEvent(string message); void WriteEvent(string message); 根据代码版本手动增加程序集的版本号，而不总是1.0。（AssemblyVersionAttribute in assemblyinfo） 如果有必要使用unsafe代码，尽量把它们写到一个单独的程序集里5.2、 变量和类型 在定义变量时，最好立即进行初始化。比如：int i=0; string s=string.Empty; 使用简单的值类型，而不是其对应的类或结构。 比如使用int而不是Int32. 只对简单类型定义常量，对于复杂类型，应定义只读或静态只读变量，在构造时进行初始化。 尽量使用泛型以避免装箱和拆箱操作 除非明确知道子类型， 应尽量避免直接类型转换， 应该使用as，并进行null检查。Example:object dataObject = LoadData();Dataset ds = dataObject as Dataset;If( ds!=null ) 在字符串前边使用符号，而不是对字符串进行逐个转义 对大量的字符串连接使用string.Format或StringBuilder. 尽量避免在未知长度的循环中使用字符串连接， 代以StringBuilder. 不要对字符串使用=和string.Empty或”进行比较， 应使用string.IsNullOrEmpty. 尽量避免字符串的隐式转换，应使用Compare方法。尤其是在循环中，可能引发较大的性能损失。ExamplePerfer BadIf( String.Compare(order.Name, name, true) If(order.Name.ToLower() = name) 避免用表达式去重复计算一个bool值Perfer BadIf( isValid ) If( isValid = true )6、 异常处理 只在你需要处理异常的地方去catch它，而不是随意的catch和重新抛出 不要使用try-catch去进行代码流控制，而是用验证去避免造成异常PerferBadIf( conn.State = ConnectionState.Open ) try Conn.Close();Conn. Close (); catch 允许异常冒泡，而不是重新抛出异常。除非你想要代之以一个自定义异常，此时应以原异常做为它的InnerException.Perfer Badcatch(Exception ex) catch(Exception ex) Log(ex) Log(ex);throw; throw ex;catch(Exception ex) catch(Exception ex) Log(ex) Log(ex);throw new CustomException(“msg”,ex);throw new CustomException(“msg”); 精选word范本！