C编码规范

C#编码规范1规范目的………………………………………………………32适用范围………………………………………………………33代码注释………………………………………………………33.1代码注释约定............................................33.2模块头部注释规范......................................33.3方法注释规范.............................................43.4代码行注释规范..........................................63.5变量注释规范.............................................74命名规则………………………………………………………84.1命名的基本约定..........................................84.2各种标示符类型的基本约定.........................94.3组件名称缩写列表.......................................105其它规范………………………………………………………115.1编程风格..................................................115.2资源释放..................................................135.3错误处理..................................................135.4其它.........................................................141规范目的1.一个软件的生命周期中，80%的花费在于维护；2.几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护；3.编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码。为了执行规范，每个软件开发人员必须一致遵守编码规范；4.使用统一编码规范的主要原因，是使应用程序的结构和编码风格标准化，以便于阅读和理解这段代码；5.好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，并且尽可能的直观。2适用范围1.本规范主要以C#为开发语言的规范；2.由于本规范是为撰写程序而设计，所以适用于一切有关程序撰写的工作事项。对于具体的每个项目，可能需要对之进行裁剪和补存。3.适用人员：软件工程专业人员；4.适用产品：以C#编写的程序。3代码注释3.1代码注释约定1.所有的方法和函数都应该以描述这段代码的功能的一段简明注释开始（方法是干什么）。这种描述不应该包括执行过程细节（它是怎么做的），因为这常常是随时间而变的，而且这种描述会导致不必要的注释维护工作，甚至更糟—成为错误的注释。代码本身和必要的嵌入注释将描述实现方法。2.当参数的功能不明显且当过程希望参数在一个特定的范围内时，也应描述传递给过程的参数。被过程改变的函数返回值和全局变量，特别是通过引用参数的那些，也必须在每个过程的起始处描述它们。3.2模块头部注释规范以一个物理文件为单元的都需要有模块头部注释规范，例如：C#中的.cs文件用于每个模块开头的说明，主要包括：（粗体字为必需部分，其余为可选部分）1.文件名称(FileName)：此文件的名称2.功能描述(Description)：此模块的功能描述与大概流程说明3.数据表(Tables)：所用到的数据表，视图，存储过程的说明，如关系比较复杂，则应说明哪些是可擦写的，哪些表为只读的。4.作者(Author)：5.日期(CreateDate)：6.参考文档(Reference)(可选)：该档所对应的分析文档，设计文檔。7.引用(Using)(可选)﹕开发的系统中引用其它系统的Dll、对象时，要列出其对应的出处，是否与系统有关﹙不清楚的可以不写﹚，以方便制作安装档。8.修改记录(RevisionHistory)：若档案的所有者改变，则需要有修改人员的名字、修改日期及修改理由。9.分割符：***************************(前后都要)示例如下：3.3方法注释规范1C#提供一种机制，使程序员可以使用含有XML文本的特殊注释语法为他们的代码编写文档。在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。具体应用当中，类、接口、属性、方法必须有Summary节，另外方法如果有参数及返回值，则必须有Param及Returns节。示例如下：///summary///…////summary///paramname=””/param///returns/returns2事件不需要头注解，但包含复杂处理时（如：循环/数据库操作/复杂逻辑等），应分割成单一处理函数，事件再调用函数。3所有的方法必须在其定义前增加方法注释。4方法注释采用///形式自动产生XML标签格式的注释。标记说明备注c提供了一种将说明中的文本标记为代码的方法code提供了一种将多行指示为代码的方法example可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到code标记的使用。exception对可从当前编译环境中获取的异常的引用。include得以引用描述源代码中类型和成员的另一文件中的注释。list用于定义表或定义列表中的标题行。para用于诸如summary、remarks或returns等标记内，使您得以将结构添加到文本中。param应当用于方法声明的注释中，以描述方法的一个参数。paramref提供了一种指示词为参数的方法。permission得以将成员的访问记入文档。remarks用于添加有关某个类型的信息，从而补充由summary所指定的信息。returns应当用于方法声明的注释，以描述返回值。see得以从文本内指定链接。seealso对可以通过当前编译环境进行调用的成员或字段的引用。summary应当用于描述类型或类型成员。value得以描述属性。示例图如下：5在公用类库中的公用方法需要在一般方法的注释后添加作者、日期及修改记录信息，统一采用XML标签的格式加注，标签如下：Author/Author作者CreateDate/CreateDate建立日期RevisionHistory修改记录ModifyBy/ModifyBy修改作者ModifyDate/ModifyDate修改日期ModifyReason/ModifyReason修改理由ModifyBy/ModifyBy修改作者ModifyDate/ModifyDate修改日期ModifyReason/ModifyReason修改理由ModifyBy/ModifyBy修改作者ModifyDate/ModifyDate修改日期ModifyReason/ModifyReason修改理由/RevisionHistoryLastModifyDate/LastModifyDate最后修改日期6一个代码文件如果是由一人编写，则此代码文件中的方法无需作者信息，非代码文件作者在此文件中添加方法时必须要添加作者、日期等注释。7修改任何方法，必须要添加修改记录的注释。3.4代码行注释规范1如果处理某一个功能需要很多行代码实现，并且有很多逻辑结构块，类似此种代码应该在代码开始前添加注释，说明此块代码的处理思路及注意事项等2注释从新行增加，与代码开始处左对齐3双斜线与注释之间以空格分开，示例图如下所示：3.5变量注释规范1定义变量时需添加变量注释，用以说明变量的用途。2Class级变量应以采用///形式自动产生XML标签格式的注释，示例图如下所示：3方法级的变量注释可以放在变量声明语句的后面，与前后行变量声明的注释左对齐，注释与代码间以Tab隔开。4命名规则4.1命名的基本约定1要使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以被命名为“i”。2要尽量采用项目所涉及领域的术语。3要采用大小写混合，提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。有两种适合的书写方法，适应于不同类型的标识符：PasalCasing：标识符的第一个单词的字母大写；camelCasing：标识符的第一个单词的字母小写。4下表描述了不同类型标识符的大小写规则：标识符大小写示例命名空间PascalnamespaceCom.Techstar.ProductionCenter类型PascalpublicclassDevsList接口PascalpublicinterfaceITableModel方法PascalpublicvoidUpdateData()属性PascalPublicintLength{…}事件PascalpubliceventEventHandlerChanged;私有字段CamelprivatestringfieldName;非私有字段PascalpublicstringFieldName；枚举值PascalFileMode{Append}参数CamelpublicvoidUpdateData(stringfieldName)局部变量CamelstringfieldName;5避免使用缩写，如果一定要使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。6对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream，getIOStream）；多字母缩写采用首字母大写，其他字母小写的方式（示例：getHtmlTag）；7避免使用长名字（最好不超过15个字母）。8避免使用相似或者仅在大小写上有区别的名字。4.2各种标示符类型的命名约定1程序集命名公司名称（Lab）+项目名称+模块名称（可选），例如：中心服务器程序集：Lab.SeverCenter；中心服务器业务逻辑程序集：Lab.SeverCenter.Business；2命名空间命名采用和程序集命名相同的方式：公司名称（Lab）+项目名称+模块名称。另外，一般情况下建议命名空间和目录结构相同。例如：中心服务器：Lab.SeverCenter；中心服务器下的用户控件：Lab.SeverCenter.UserControl；中心服务器业务逻辑：Lab.SeverCenter.Business；中心服务器数据访问：Lab.SeverCenter.Data；3程序集和DLLl大多数情况下，程序集包含全部或部分可重用库，且它包含在单个动态链接库(DLL)中。l一个程序集可拆分到多个DLL中，但这非常少见，在此准则中也没有说明。l程序集和DLL是库的物理组织，而命名空间是逻辑组织，其构成应与程序集的组织无关。l命名空间可以且经常跨越多个程序集。可以考虑如下模式命名DLL：Company.Component.dll例：Lab.SeverCenter.dll4类和接口命名l类的名字要用名词；l避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。l接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent接口的标准实现为Component；l泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：publicclassListTpublicclassMyClassTsessionl对同一项目的不同命名空间