《C#代码编写规范》由会员分享,可在线阅读,更多相关《C#代码编写规范(22页珍藏版)》请在金锄头文库上搜索。
1、1. 简介 本规范为一套编写高效可靠的 C# 代码的标准、约定和指南。它以安全可靠的软件工程原则为基础,使代码易于理解、维护和增强,提高生产效率。同时,将带来更大的一致性,使软件开发团队的效率明显提高。 2. 适用范围 本规范适用于公司所有的 C#源代码,为详细设计,代码编写和代码审核提供参考和依据。 3. 文体 本规范中的建议分为四种:要,建议,避免,不要,表示需要遵循的级别。文档中会以粗体表示。对于应遵循的规范,前面会以 “”来表示,对不好的做法前面会以 “”来表示: 要:描述必须遵循的规范。例如: 异常类要 以 “Exception”做为后缀; 建议:描述在一般情况下应该遵循的规范,但如
2、果完全理解规范背后的道理,并有很好的理由不遵循它时,也不畏惧打破常规。例如: 强制类型转换时,在类型和变量之间建议加一空格。 不要:描述一些几乎绝对绝不应该违反的规范。例如: 每个函数有效代码(不包括注释和空行)长度不要超过 50 行。 避免:与建议相对,一般情况下应该遵循,但有很好的理由时也可以打破。例如: 避免块内部的变量与它外部的变量名相同。 对一些规范内容一并提供了示例代码。 4. 代码组织与风格 4.1. Tab 要使一个 Tab 为 4 个空格长。 4.2. 缩进 要使一个代码块内的代码都统一缩进一个 Tab 长度。 4.3. 空行 建议适当的增加空行,来增加代码的可读性。 在在类
3、,接口以及彼此之间要有两行空行: 在下列情况之间要有一行空行: 方法之间; 局部变量和它后边的语句之间; 方法内的功能逻辑部分之间; 4.4. 函数长度 每个函数有效代码(不包括注释和空行)长度不要超过 50 行。 4.5. ”, “” 开括号 “”要放在块的所有者的下一行,单起一行; 闭括号 “”要单独放在代码块的最后一行,单起一行。 4.6. 行宽 每行代码和注释不要超过 70个字符或屏幕的宽度,如超过则应换行,换行后的代码应该缩进一个 Tab。 4.7. 空格 括号和它里面的字符之间不要出现空格。括号应该和它前边的关键词留有空格,如: while (true) ; 但是方法名和左括号之间
4、不要有空格。 参数之间的逗号后要加一空格。如: method1(int i1, int i2) for 语句里的表达式之间要加一空格。如: for (expr1; expr2; expr3) 二元操作符和操作数之间要用空格隔开。如: i + c; 强制类型转换时,在类型和 变量之间要加一空格。如: (int) i ; 5. 注释 5.1. 注释的基本约定 注释应该增加代码的清晰度; 保持注释的简洁,不是任何代码都需要注释的,过多的注释反而会影响代码的可读性。 注释不要包括其他的特殊字符。 建议先写注释,后写代码,注释和代码一起完成 如果语句块(比如循环和条件分枝的代码块)代码太长,嵌套太多,则
5、在其结束 “ ”要加上注释,标志对应的开始语句。如果分支条件逻辑比较复杂,也要加上注释。 在 VS2010 环境中通过配置工程编译时输出 XML 文档文件可以检查注释的完整情况,如果注释不完整会报告 编译警告; 5.2. 注释类型 5.2.1. 文件头注释 参见 截图: 5.2.2. 块注释 主要用来描述文件,类,方法,算法等,放在所描述对象的前边。具体格式以 IDE 编辑器输入 “/”自动生成的格式为准 。 对类和接口的注释必须加上上述标记,对方法可以视情况考虑 5.2.3. 行注释 主要用在方法内部,对代码,变量,流程等进行说明。整个注释占据一行。 5.2.3. 尾随注释 与行注释功能相似
6、,放在代码的同行,但是要与代码之间有足够的空间,便于分清。例: int m = 4 ; / 注释 如果一个程序块内有多个尾随注释,每个注释的缩进要保持一致。 5.3. 注释哪些部分 项目 注释哪些部分 参数 参数用来做什么 任何约束或前提条件 字段 /属性 字段描述 类 类的目的 , 已知的问题 , 类的开发 /维护历史 接口 目的 , 它应如何被使用以及如何不被使用 局部变量 用处 /目的 成员函数注释 成员函数做什么以及它为什么做这个 哪些参数必须传递给一个成员函数 ,成员函数返回什么 , 已知的问题 , 任何由某个成员函数抛出的异常 成员函数是如何改变对象的 , 包含任何修改代码的历史
7、, 如何 在适当情况下调用成员函数的例子适用的前提条件和后置条件 成员函数内部注释 控制结构 , 代码做了些什么以及为什么这样做 , 局部变量 , 难或复杂的代码 , 处理顺序 5.4. 程序修改注释 新增代码行的前后要有注释行说明,对具体格式不作要求,但必须包含作者,新增时间,新增目的。在新增代码的最后必须加上结束标志; 删除代码行的前后要用注释行说明,删除代码用注释原有代码的方法。注释方法和内容同新增;删除的代码行建议用 #region XXX #endregion 代码段折叠,保持代码文件干净整洁 修改代码行建议以删除代码 行后再新增代码行的方式进行(针对别人的代码进行修改时,必须标明,
8、对于自己的代码进行修改时,酌情进行)。注释方法和内容同新增; 6. 命名 6.1. 命名的基本约定 要使用可以准确说明变量 /字段 /类的完整的英文描述符,如 firstName。对一些作用显而易见的变量可以采用简单的命名,如在循环里的递增(减)变量就可以被命名为 ” i ”。 要尽量采用项目所涉及领域的术语。 要采用大小写混合,提高名字的可读性。为区分一个标识符中的多个单词,把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。有两种适合 的书写方法,适应于不同类型的标识符: PasalCasing:标识符的第一个单词的字母大写; camelCasing:标识符的第一个单词的字母小
9、写。 下表描述了不同类型标识符的大小写规则: 标识符 大小写 示例 命名空间 Pascal namespace Com.Techstar.ProductionCenter 类型 Pascal public class DevsList 接口 Pascal public interface ITableModel 方法 Pascal public void UpdateData() 属性 Pascal Public int Length 事件 Pascal public event EventHandler Changed; 私有字段 Camel private string fieldName
10、; 非私有字段 Pascal public string FieldName; 枚举值 Pascal FileModeAppend 参数 Camel public void UpdateData(string fieldName) 局部变量 Camel string fieldName; 避免使用缩写,如果一定要使用,就谨慎使用。同时,应该保留一个标准缩写的列表,并且在使用时保持一致。 对常见缩略词,两个字母的缩写要采用统一大小写的方式(示例: ioStream, getIOStream);多字母缩写采用首字母大写,其他字母小写的方式(示例: getHtmlTag); 避免使用长名字(最好不超
11、过 15 个字母)。 避免使用相似或者仅在大小写上有区别的名字。 6.2. 各种标示符类型的命名约定 6.2.1. 程序集命名 公司 名 Funsing 我们 简写 为 ( FS) + 项 目名称 + 模块名称(可选),例如: 佳音 体检 系统 业务 逻辑 程序集: FS.JYPEIS.BL; 佳音 体检 系统 数据 访问 程序集 : FS.JYPEIS.DataAccess; 6.2.2. 命名空间命名 采用和程序集命名相同的方式: 公司 名 Funsing 我们 简写 为 ( FS) + 项目名称 + 模块名称。 另外,一般情况下建议命名空间和目录结构相同。例如: 数据 访问 适配 层 :
12、 FS.JYPEIS.CommonDAL; 6.2.3. 类和接口命名 类的名字要用名词; 避免使用单词的缩写,除非它的缩写已经广为人知,如 HTTP。 接口的名字要以字母 I 开头。保证对接口的标准实现名字只相差一个 “I”前缀,例如对 IComponent 的标准实现为 Component; 泛型类型参数的命名:命名要为 T 或者以 T 开头的描述性名字,例如: public class List public class MyClass 对同一项目的不同命名空间中的类,命名避免重复。避免引用时的冲突和混淆; 6.2.4. 方法命名 第一个单词一般是动词 如果方法返回一个成员变量的值,方法
13、名一般为 Get+成员变量名,如若返回的值 是 bool 变量,一般以 Is 作为前缀。另外,如果必要,考虑用属性来替代方法,具 体建议见 10.1.2 节 ; 如果方法修改一个成员变量的值,方法名一般为: Set + 成员变量名。同上,考虑 用属性来替代方法; 6.2.5. 变量 命名 按照使用范围来分,我们代码中的变量的基本上有以下几种类型,类的公有变量;类的私有变量(受保护同公有);方法的参数变量;方法内部使用的局部变量。这些变量的命名规则基本相同,见标识符大小写对照表。区别如下: i. 类的公有变量按通常的方式命名,无特殊要求; ii. 类的私有变量采用两种方式均可:采用加 “m”前缀
14、,例如 mWorkerName; iii. 方法的参数变量采用 camalString,例如 workerName; iv. 方法内部的局部变量采用 camalString,例如 workerName; 不要 用 _或 &作为第一个字母; 尽量要使用短而且具有意义的单词; 单字符的变量名一般只用于生命期非常短暂的变量。 i,j,k,m,n 一般用于 integer; c,d,e 一般用于characters; s 用于 string 如果变量是集合,则变量名要用复数。例如表格的行数,命名应为: RowsCount; 命名组件要采用匈牙利命名法,所有前缀均应遵循同一个组件名称缩写列表 6.3.
15、组件名称缩写列表 缩写的基本原则是取组件类名各单词的第一个字母,如果只有一个单词,则去掉其中的元音,留下辅音。缩写全部为小写。 组件类型 缩写 例子 Label Lb LbNote TextBox Tb TbName Button Btn BtnOK ImageButton Ib IbOK LinkButton Lb LbJump HyperLink Hl HlJump DropDownList Dd DdlList CheckBox Cb CbChoice CheckBoxList Cbl CblGroup RadioButton Rb RbChoice RadioButtonList Rbl RblGroup Image Img ImgBeauty Panel Pnl PnlTree TreeView Tv TvUnit ComboBox Cb CbList PageBar Pb PbMaster GridView Gv GvData DataList Dl DlData 7. 声明 每行要只有一个声明,如果是声明 i,j,k 之类的简单变量可以放在一行 ; 除了 for 循环外,声明要放在块的最开始部分。 for 循环中的变量声明可以放在 for 语句中。如: for(int i = 0; I 10; i+) 。 避免块内部的变量与它外部的