C# 编码规范、命名规则

1  规范目的 ……………………………………………………… 3

2  适用范围 ……………………………………………………… 3

3  代码注释 ……………………………………………………… 3

　　3.1    代码注释约定............................................ 3

　　3.2    模块头部注释规范...................................... 3

　　3.3    方法注释规范............................................. 4

　　3.4    代码行注释规范.......................................... 6

　　3.5    变量注释规范............................................. 7

4  命名规则 ……………………………………………………… 8

　　4.1    命名的基本约定.......................................... 8

　　4.2    各类标示符类型的基本约定......................... 9

　　4.3    组件名称缩写列表....................................... 10

5  其它规范 ……………………………………………………… 11

　　5.1    编程风格.................................................. 11

　　5.2    资源释放.................................................. 13

　　5.3    错误处理.................................................. 13

　　5.4    其它......................................................... 14

 

 

1     规范目的

1. 一个软件的生命周期中，80%的花费在于维护；
2. 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护；
3. 编码规范能够改善软件的可读性，可让程序员尽快而完全地理解新的代码。为了执行规范，每一个软件开发人员必须一致遵照编码规范；
4. 使用统一编码规范的主要缘由，是使应用程序的结构和编码风格标准化，以便于阅读和理解这段代码；
5. 好的编码约定可以使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，而且尽量的直观。

 

2     适用范围

1. 本规范主要以C#为开发语言的规范，为鲍亮实验室的原则性规范；
2. 因为本规范是为撰写程序而设计，因此适用于一切有关程序撰写的工做事项。对于具体的每一个项目，可能须要对之进行裁剪和补存。
3. 适用人员：软件工程专业的学生；
4. 适用产品：以C#编写的程序。

 

3     代码注释

3.1    代码注释约定

1. 全部的方法和函数都应该以描述这段代码的功能的一段简明注释开始（方法是干什么）。这种描述不该该包括执行过程细节（它是怎么作的），由于这经常是随时间而变的，并且这种描述会致使没必要要的注释维护工做，甚至更糟—成为错误的注释。代码自己和必要的嵌入注释将描述实现方法。
2. 当参数的功能不明显且当过程但愿参数在一个特定的范围内时，也应描述传递给过程的参数。被过程改变的函数返回值和全局变量，特别是经过引用参数的那些，也必须在每一个过程的起始处描述它们。

3.2     模块头部注释规范

以一个物理文件为单元的都须要有模块头部注释规范，例如：C#中的.cs文件

用于每一个模块开头的说明，主要包括：（粗体字为必需部分，其他为可选部分）

1. 文件名称(File Name)： 此文件的名称
2. 功能描述(Description)：   此模块的功能描述与大概流程说明
3. 数据表(Tables)：             所用到的数据表，视图，存储过程的说明，如关系比较复杂，则应说明哪些是可擦写的，哪些表为只读的。
4. 做者(Author)：
5. 日期(Create Date)：
6. 参考文档(Reference)(可选)：          该档所对应的分析文档，设计文檔。
7. 引用(Using) (可选)﹕           开发的系统中引用其它系统的Dll、对象时，要列出其对应的出处，是否与系统有关﹙不清楚的能够不写﹚，以方便制做安装档。
8. 修改记录(Revision History)：若档案的全部者改变，则须要有修改人员的名字、修改日期及修改理由。
9. 分割符：*************************** (先后都要)

示例以下：

　　

3.3     方法注释规范

　　1>  C# 提供一种机制，使程序员可使用含有XML 文本的特殊注释语法为他们的代码编写文档。在源代码文件中，具备某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。具体应用当中，类、接口、属性、方法必须有<Summary>节，另外方法若是有参数及返回值，则必须有<Param>及<Returns>节。示例以下：

　　　　/// <summary>
　　　　/// … 　　　　/// </summary>
　　　　/// <param name=””></param>
　　　　/// <returns></returns>

　　2>  事件不须要头注解，但包含复杂处理时（如：循环/数据库操做/复杂逻辑等），应分割成单一处理函数，事件再调用函数。

　　3>  全部的方法必须在其定义前增长方法注释。

　　4>  方法注释采用 /// 形式自动产生XML标签格式的注释。

 

　　　　示例图以下：

　　　

　　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>
</RevisionHistory>
<LastModifyDate>最后修改日期</LastModifyDate>

　　6>  一个代码文件若是是由一人编写，则此代码文件中的方法无需做者信息，非代码文件做者在此文件中添加方法时必需要添加做者、日期等注释。

　　7>  修改任何方法，必需要添加修改记录的注释。

3.4     代码行注释规范

　　1>  若是处理某一个功能须要不少行代码实现，而且有不少逻辑结构块，相似此种代码应该在代码开始前添加注释，说明此块代码的处理思路及注意事项等

　　2>  注释重新行增长，与代码开始处左对齐　　

　　3>  双斜线与注释之间以空格分开，示例图以下所示：

　　

3.5     变量注释规范

　　1>  定义变量时需添加变量注释，用以说明变量的用途。

　　2>  Class级变量应以采用 /// 形式自动产生XML标签格式的注释，示例图以下所示：　　                                                                                                

　　3>  方法级的变量注释能够放在变量声明语句的后面，与先后行变量声明的注释左对齐，注释与代码间以Tab隔开。

 

4    命名规则

4.1     命名的基本约定

　　1>  要使用能够准确说明变量/字段/类的完整的英文描述符，如firstName。对一些做用显而易见的变量能够采用简单的命名，如在循环里的递增（减）变量就能够被命名为 “i”。

　　2>  要尽可能采用项目所涉及领域的术语。

　　3>  要采用大小写混合，提升名字的可读性。为区分一个标识符中的多个单词，把标识符中的每一个单词的首字母大写。不采用下划线做分隔字符的写法。

　　　　有两种适合的书写方法，适应于不一样类型的标识符：

　　　　　　PasalCasing：标识符的第一个单词的字母大写；

　　　　　　camelCasing：标识符的第一个单词的字母小写。

　　4>  下表描述了不一样类型标识符的大小写规则：

　　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>  程序集和DLL

　　l  大多数状况下，程序集包含所有或部分可重用库，且它包含在单个动态连接库(DLL) 中。

　　l  一个程序集可拆分到多个DLL 中，但这很是少见，在此准则中也没有说明。

　　l  程序集和DLL 是库的物理组织，而命名空间是逻辑组织，其构成应与程序集的组织无关。

　　l  命名空间能够且常常跨越多个程序集。能够考虑以下模式命名DLL：

      　　  <Company>.<Component>.dll

   　　     例：Lab.SeverCenter.dll

　　4> 类和接口命名

　　l  类的名字要用名词；

　　l  避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。

　　l  接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent接口的标准实现为Component；

　　l  泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：

　　　　public class List<T>

　　　　public class MyClass<Tsession>

　　l  对同一项目的不一样命名空间中的类，命名避免重复。避免引用时的冲突和混淆；

　　5> 方法命名

　　l  第一个单词通常是动词；

　　l  若是方法返回一个成员变量的值，方法名通常为Get+成员变量名，如若返回的值 是bool变量，通常以Is做为前缀。另外，若是必要，考虑用属性来替代方法；

　　l  若是方法修改一个成员变量的值，方法名通常为：Set + 成员变量名。同上，考虑 用属性来替代方法。

　　6> 变量命名

　　l  按照使用范围来分，咱们代码中的变量的基本上有如下几种类型，类的公有变量；类的私有变量（受保护同公有）；方法的参数变量；方法内部使用的局部变量。这些变量的命名规则基本相同，见标识符大小写对照表。区别以下：

　　　　a)   类的公有变量按一般的方式命名，无特殊要求；

　　　　b)   类的私有变量采用两种方式都可：采用加“m”前缀，例如mWorkerName;

　　　　c)   方法的参数变量采用camalString，例如workerName；

　　l  方法内部的局部变量采用camalString，例如workerName。

　　l  不要用_或&做为第一个字母；

　　l  尽可能要使用短并且具备意义的单词；

　　l  单字符的变量名通常只用于生命期很是短暂的变量：i,j,k,m,n通常用于integer；c,d,e 通常用于characters；s用于string

　　l  若是变量是集合，则变量名要用复数。例如表格的行数，命名应为：RowsCount；

　　l  命名组件要采用匈牙利命名法，全部前缀均应遵循同一个组件名称缩写列表

4.3  组件名称缩写列表

　　缩写的基本原则是取组件类名各单词的第一个字母，若是只有一个单词，则去掉其中的元音，留下辅音。缩写所有为小写。

 

5    其它规范

5.1      编程风格

　　1>  变量声明：

　　为了保持更好的阅读习惯，请不要把多个变量声明写在一行中，即一行只声明一个变量。

　　--例如： 　　String strTest1, strTest2; 　　--应写成： 　　String strTest1; 　　String strTest2;

　　2>   代码缩进：

　　l  一致的代码缩进风格，有利于代码的结构层次的表达，使代码更容易阅读和传阅；

　　l  代码缩进使用Tab键实现，最好不要使用空格，为保证在不一样机器上使代码缩进保持一致，特此规定C#的Tab键宽度为4个字符，设定界面以下(工具–选项)：

　　

　　l  避免方法中有超过5个参数的状况，通常以2,3个为宜。若是超过了，则应使用struct来传递多个参数。

　　l  为了更容易阅读，代码行请不要太长，最好的宽度是屏幕宽度（根据不一样的显示分辩率其可见宽度也不一样）。请不要超过您正在使用的屏幕宽度。（每行代码不要超过80个字符。）

　　l  程序中不该使用goto语句。

　　l  在switch语句中老是要default子句来显示信息。

　　l  方法参数多于8个时采用结构体或类方式传递

　　l  操做符/运算符左右空一个半角空格

　　l  全部块的{}号分别放置一行，并嵌套对齐，不要放在同一行上 

　　3>    空白：

　　l  空行将逻辑相关的代码段分隔开，以提升可读性。

　　l  下列状况应该老是使用两个空行：

　　　　a)  一个源文件的两个片断(section)之间。

　　　　b)  类声明和接口声明之间。

　　l  下列状况应该老是使用一个空行：

　　　　a)  两个方法之间。

　　　　b)  方法内的局部变量和方法的第一条语句之间。

　　　　c)  块注释（参见"5.1.1"）或单行注释（参见"5.1.2"）以前。

　　　　d)  一个方法内的两个逻辑段之间，用以提升可读性。

　　l  下列状况应该老是使用空格：

　　　　a)  空白应该位于参数列表中逗号的后面，如：

　　　　　　void UpdateData(int a, int b)

　　　　b)  全部的二元运算符，除了"."，应该使用空格将之与操做数分开。一元操做符和操做数之间不因该加空格，好比：负号("-")、自增("++")和自减("--")。例如：

　　　　　　　　a += c + d;

　　　　　　　　d++;

　　　　c)  for 语句中的表达式应该被空格分开，例如：

　　　　　　　　for (expr1; expr2; expr3)

　　　　d)  强制转型后应该跟一个空格，例如：

　　　　　　　　char c;

　　　　　　　　int a = 1;

　　　　　　　　c = (char) a;

5.2     资源释放

　　全部外部资源都必须显式释放。例如：数据库链接对象、IO对象等。

　　

5.3     错误处理

　　1>  不要“捕捉了异常却什么也不作“。若是隐藏了一个异常，你将永远不知道异常到底发生了没有。

　　2>  发生异常时，给出友好的消息给用户，但要精确记录错误的全部可能细节，包括发生的时间，和相关方法，类名等。

　　3>  只捕捉特定的异常，而不是通常的异常。

　　正确作法：

　　

　　错误作法：

　　

5.4     其它

　　1>  一个方法只完成一个任务。不要把多个任务组合到一个方法中，即便那些任务很是小。

　　2>  使用C#的特有类型，而不是System命名空间中定义的别名类型。

　　3>  别在程序中使用固定数值，用常量代替。

　　4>  避免使用不少成员变量。声明局部变量，并传递给方法。不要在方法间共享成员变量。若是在几个方法间共享一个成员变量，那就很难知道是哪一个方法在何时修改了它的值。

　　5>  别把成员变量声明为 public 或 protected。都声明为 private 而使用 public/protected 的属性

　　6>  不在代码中使用具体的路径和驱动器名。 使用相对路径，并使路径可编程。

　　7>  应用程序启动时做些“自检”并确保所需文件和附件在指定的位置。必要时检查数据库链接。出现任何问题给用户一个友好的提示。

　　8>  若是须要的配置文件找不到，应用程序需能本身建立使用默认值的一份。

　　9>  若是在配置文件中发现错误值，应用程序要抛出错误，给出提示消息告诉用户正确值。

　　10>  DataColumn取其列时要用字段名，不要用索引号。
　　　　例： 正确DataColumn[“Name”]
    　　　　  很差 DataColumn[0]

　　11>  在一个类中，字段定义所有统一放在class的头部、全部方法或属性的前面。

　　12>  在一个类中，全部的属性所有定义在一个属性块中：