C#代码规范

目录1.简介.......................................................................................................22.适用范围..............................................................................................23.文体.......................................................................................................24.代码组织与风格..................................................................................25.注释.......................................................................................................46.命名.......................................................................................................67.声明.....................................................................................................138.表达式和语句....................................................................................139.类型设计规范....................................................................................1610.成员设计规范..................................................................................1811.扩展性设计规范..............................................................................2312.异常处理规范..................................................................................2413.其他规定..........................................................................................2514.参考文档..........................................................................................261.简介本规范为一套编写高效可靠的C#代码的标准、约定和指南。它以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强，提高生产效率。同时，将带来更大的一致性，使软件开发团队的效率明显提高。2.适用范围本规范适用于公司所有的C#源代码，为详细设计，代码编写和代码审核提供参考和依据。3.文体本规范中的建议分为四种：要，建议，避免，不要，表示需要遵循的级别。文档中会以粗体表示。对于应遵循的规范，前面会以“Ö”来表示，对不好的做法前面会以“´”来表示：要：描述必须遵循的规范。例如：异常类要以“Exception”做为后缀；建议：描述在一般情况下应该遵循的规范，但如果完全理解规范背后的道理，并有很好的理由不遵循它时，也不畏惧打破常规。例如：强制类型转换时，在类型和变量之间建议加一空格。不要：描述一些几乎绝对绝不应该违反的规范。例如：每个函数有效代码（不包括注释和空行）长度不要超过50行。避免：与建议相对，一般情况下应该遵循，但有很好的理由时也可以打破。例如：避免块内部的变量与它外部的变量名相同。对一些规范内容一并提供了示例代码。4.代码组织与风格4.1.Tab要使一个Tab为4个空格长。4.2.缩进要使一个代码块内的代码都统一缩进一个Tab长度。4.3.空行建议适当的增加空行，来增加代码的可读性。在在类，接口以及彼此之间要有两行空行：在下列情况之间要有一行空行：方法之间；局部变量和它后边的语句之间；方法内的功能逻辑部分之间；4.4.函数长度每个函数有效代码（不包括注释和空行）长度不要超过50行。4.5.“{”，“}”开括号“{”要放在块的所有者的下一行，单起一行；闭括号“}”要单独放在代码块的最后一行，单起一行。4.6.行宽每行代码和注释不要超过70个字符或屏幕的宽度，如超过则应换行，换行后的代码应该缩进一个Tab。4.7.空格括号和它里面的字符之间不要出现空格。括号应该和它前边的关键词留有空格，如：while(true){};但是方法名和左括号之间不要有空格。参数之间的逗号后要加一空格。如：method1(inti1,inti2)for语句里的表达式之间要加一空格。如：for(expr1;expr2;expr3)二元操作符和操作数之间要用空格隔开。如：i+c;强制类型转换时，在类型和变量之间要加一空格。如：(int)i;5.注释5.1.注释的基本约定注释应该增加代码的清晰度；保持注释的简洁，不是任何代码都需要注释的，过多的注释反而会影响代码的可读性。注释不要包括其他的特殊字符。建议先写注释，后写代码，注释和代码一起完成如果语句块（比如循环和条件分枝的代码块）代码太长，嵌套太多，则在其结束“｝”要加上注释，标志对应的开始语句。如果分支条件逻辑比较复杂，也要加上注释。在VS2005环境中通过配置工程编译时输出XML文档文件可以检查注释的完整情况，如果注释不完整会报告编译警告；5.2.注释类型5.2.1.块注释主要用来描述文件，类，方法，算法等，放在所描述对象的前边。具体格式以IDE编辑器输入“///”自动生成的格式为准，另外再附加我们自定义的格式，如下所列：///Remark作者，创建日期，修改日期/Remark对类和接口的注释必须加上上述标记，对方法可以视情况考虑5.2.2.行注释主要用在方法内部，对代码，变量，流程等进行说明。整个注释占据一行。5.2.3.尾随注释与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：intm=4;//注释如果一个程序块内有多个尾随注释，每个注释的缩进要保持一致。5.3.注释哪些部分项目注释哪些部分参数参数用来做什么任何约束或前提条件字段/属性字段描述类类的目的已知的问题类的开发/维护历史接口目的它应如何被使用以及如何不被使用局部变量用处/目的成员函数注释成员函数做什么以及它为什么做这个哪些参数必须传递给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函数的例子适用的前提条件和后置条件成员函数内部注释控制结构代码做了些什么以及为什么这样做局部变量难或复杂的代码处理顺序5.4.程序修改注释新增代码行的前后要有注释行说明，对具体格式不作要求，但必须包含作者，新增时间，新增目的。在新增代码的最后必须加上结束标志；删除代码行的前后要用注释行说明，删除代码用注释原有代码的方法。注释方法和内容同新增；删除的代码行建议用#regionXXX#endregion代码段折叠，保持代码文件干净整洁修改代码行建议以删除代码行后再新增代码行的方式进行（针对别人的代码进行修改时，必须标明，对于自己的代码进行修改时，酌情进行）。注释方法和内容同新增；6.命名6.1.命名的基本约定要使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以被命名为“i”。要尽量采用项目所涉及领域的术语。要采用大小写混合，提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。有两种适合的书写方法，适应于不同类型的标识符：PasalCasing：标识符的第一个单词的字母大写；camelCasing：标识符的第一个单词的字母小写。下表描述了不同类型标识符的大小写规则：标识符大小写示例命名空间PascalnamespaceCom.Techstar.ProductionCenter类型PascalpublicclassDevsList接口PascalpublicinterfaceITableModel方法PascalpublicvoidUpdateData()属性PascalPublicintLength{…}事件PascalpubliceventEventHandlerChanged;私有字段CamelprivatestringfieldName;非私有字段PascalpublicstringFieldName；枚举值PascalFileMode{Append}参数CamelpublicvoidUpdateData(stringfieldName)局部变量CamelstringfieldName;避免使用缩写，如果一定要使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream，getIOStream）；多字母缩写采用首字母大写，其他字母小写的方式（示例：getHtmlTag）；避免使用长名字（最好不超过15个字母）。避免使用相似或者仅在大小写上有区别的名字。6.2.各种标示符类型的命名约定6.2.1.程序集命名公司域名（Techstar）+项目名称+模块名称（可选），例如：中心系统程序集：Techstar.ProductionCenter；中心系统业务逻辑程序集：Techstar.ProductionCenter.Business；6.2.2.命名空间命名采用和程序集命名相同的方式：公司域名（Techstar）+项目名称+模块名称。另外，一般情况下建议命名空间和目录结构相同。例如：中心系统：Techstar.ProductionCenter；中心系统下的用户控件：Techstar.ProductionCenter.UserControl；中心系统业务逻辑：Techstar.ProductionCenter.Business；中心系统数据访问：Techstar.ProductionCenter.Data；6.2.3.类和接口命名类的名字要用名词；避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent的标准实现为Component；泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：publicclassListTpublicclassMyClassTSession´对同一项目的不同命名空间中的类，命名避免重复。避免引用时的冲突和混淆；6.2.4.方法命名第一个单词一般是动词如果方法返回一个成员变量的值，方法名一般为Get+成员变量名，如若返回的值是bool变量，一般以Is作为前缀。另外，如果必要，考虑用属性来替代方法，具体建议见10.1.2节;如果方法修改一个成员变量的值，方法名一般为：Set+成员变量名。同上，考虑用属性来替代方法；6.2.5.变量命名按照使用范围来分，我们代码中的变量的基本上有以下几种类型，类的公有变量；类