C# 编码规范说明书

1、C#编编码码规规范范 说说明明书书 方方正正国国际际公公安安与与地地理理信信息息事事业业部部 2 20 01 11 1 年年 6 6 月月 文文档档修修订订说说明明表表 序序 号号 版版本本产产品品版版本本修修订订内内容容修修订订人人审审核核人人修修订订时时间间备备注注 1V1.0V文档创建杨凤霞2011-07-08 2 3 4 5 目目 录录 1 目标目标.3 2概述概述 .3 3总体要求总体要求 .3 3.1程序结构化.3 3.2代码可读性.3 3.3代码结构化.4 3.4正确性与容错性.4 4编码规范编码规范 .4 4.1文件结构.4 4.1.1C# 文件文件.4 4.1.

2、2目录结构目录结构.4 4.2缩进.5 4.2.1换行换行.5 4.2.2空格空格.5 4.3注释.6 4.3.1模块注释模块注释.6 4.3.2单行注释单行注释.6 4.3.3类注释类注释.6 4.3.4方法注释方法注释.6 4.4声明.7 4.4.1单行声明变量数单行声明变量数.7 4.4.2初始化初始化.7 4.4.3类和接口声明类和接口声明.7 4.5功能语句.8 4.5.1简单逻辑简单逻辑.8 4.5.2if-else语句语句.8 4.5.3For / Foreach 语句语句.9 4.5.4While/do-while 语句语句.9 4.5.5Switch 语句语句.9 4.5.6

3、Try-catch 语句语句.10 4.6空白.10 4.6.1空白行空白行.10 4.6.2参数条件之间的空白参数条件之间的空白.11 4.6.3表格式的样式表格式的样式.11 4.7命名规范.12 4.7.1大写大写.12 Pascal 风格风格.12 驼峰规则驼峰规则.12 大写风格大写风格.12 4.7.2命名方法命名方法.12 类命名类命名.12 接口命名接口命名.12 枚举命名枚举命名.13 常量命名常量命名.13 参数命名参数命名.13 变量命名变量命名.

4、13 方法命名方法命名.13 属性命名属性命名.13 事件命名事件命名.13 0大写风格大写风格.13 4.8开发习惯.14 4.8.1可见性可见性.14 4.8.2不要硬编码数字不要硬编码数字.14 4.9代码示例.14 4.9.1作用域（作用域（“”）示例）示例.14 5控件命名规范以及一般用法控件命名规范以及一般用法 .15 6参考参考 .18 7附录附录 .18 7.1XML 注释标记的使用.18 8 修改历史修改历史.21 1目目标标 为本部门 DotNet 组的 C#程序员制定一个统一的编码规范，最大限度减少不同程序员开发 的

5、代码间的差异。 2概概述述 为了使应用程序的结构和编码风格标准化，便于阅读和理解编码，以提高开发效率和 产品的标准化，制订一套开发规范和标准势在必行。此外，好的编码约定可使源代码严谨、 可读性强且意义清楚，与其它语言约定相一致，并且尽可能的直观。希望开发人员严格遵 守此套开发规范和标准，并落实到自己的程序中。 本规范主要针对 C#程序员，但是其中许多规则同时适用于其他语言的程序员。 3总总体体要要求求 3.1程程序序结结构构化化 程序结构清晰，函数功能简单易懂（单个函数的代码行数不超过 100 行） 3.2代代码码可可读读性性 保持注释与代码完全一致 每个源程序文件，都有文件头说明，详细见下节

6、 每个函数，都有函数头说明，详细见下节 主要变量（结构、联合、类或对象）定义或引用时，注释能反映其含义 处理过程的每个阶段都有相关注释说明 在典型算法前都有注释, 同时算法在满足要求的情况下尽可能简单 利用缩进来显示程序的逻辑结构，缩进量一致并以 Tab 键为单位，定义 Tab 为 4 个字节 循环、分支层次一般不应超过五层 代码简单的分支应该写在前面 不允许同行出现两个语句 空行和空白字符也是一种特殊注释 一目了然的语句不加注释 注释的作用范围可以为：定义、引用、条件分支以及一段代码 常量定义（DEFINE）有相应说明 3.3代代码码结结构构化化 禁止 GOTO 语句 用 CASE 实现多路

7、分支 避免不必要的分支 用 IF 语句来强调只执行两组语句中的一组。尽量不使用 Else Return 尽量避免从循环引出多个出口 3.4正正确确性性与与容容错错性性 所有变量在调用前必须被初始化 不要比较浮点数的相等，如： 10.0 * 0.1 = 1.0 ， 不可靠 访问外部资源(数据库，外部文件)时使用规范的容错语句 例如: try catch finally 4编编码码规规范范 4.1文文件件结结构构 4.1.1C# 文文件件 尽量不要让你的类或者文件太长,一般不应超过 2000 行代码。请按照功能划分你的代码， 使结构保持清晰。一般情况下，一个文件应当只有一个类，并且文件名应该与类名

8、保持一致。 4.1.2目目录录结结构构 应该为每个名称空间(namespace)建立一个目录(例如，我们可以为名称空间 MyProject.TestSuite.TestTier 建立这样的目录：MyProject/TestSuite/TestTier)。这样做可以 让你很快定位到指定名称空间下的类文件。 4.2缩缩进进 4.2.1换换行行 如果表达式太长而一行无法写下时，请按照下列规范进行换行： 可以在逗号后面进行换行 可以在操作符号后进行换行 尽量选择在较高层处进行换行 换行后的新行应当与前一行中同级别的运算符对齐 例子： 方法调用换行： longMethodCall(expr1, expr

9、2, expr3, expr4, expr5); 算术表达式换行： 规范的: var = a * b / (c - g + f) + 4 * z; 不规范的: var = a * b / (c - g + f) + 4 * z; 上面第一个表达式的换行方式是符合规范的，它换行在括号外面（较高层）。另外请注 意，换行后的新行应使用 tab 和空格保持与前一行的同级运算符对齐，例如: var = a * b / (c - g + f) + .4 * z; 表示 Tab 符， .表示空格。你可以设置你的编辑环境，使 Tab 和空格在编辑时是可 见的，这是一个不错的习惯。 4.2.2空空格格 我们选择

10、 Tab 缩进作为缩进时采用的标准。 请不要使用空格代替请不要使用空格代替 Tab 键键! 4.3注注释释 4.3.1 模模块块注注释释 在一个程序模块的开始，应用注释说明模块的名字、功能、开发者和日期和版本变更历史， 如下所示： /* * Copyright(c) Suzsoft DotNet Group * Description : Tenant access class * CreateDate : 2006-06-02 05:03:46 * Creater : Johnson Cao * LastChangeDate: * LastChanger : * Version Info :

11、 1.0 * */ 4.3.2单单行行注注释释 程序员应当在算法比较复杂的表达式前、特殊含义的变量前或者在一整段功能代码开始之 前添加适当的注释。我们要求这样的单行 注释采用”/”符号，例如： / Calculate subTotal Decimal subTotal = 0; 4.3.3类类注注释释 在定义一个类之前，应用“/”注释说明类的功能、使用方法和特殊的属性，如下所 示： / / This class. / / Please note / / 详细的 xml 注释标记的使用请参见附录。 4.3.4方方法法注注释释 在定义类成员方法前，应说明该过程/函数的名字、功能、输入/输出和版本变

12、更历史，如 下所示： / / This method . / this is a param of the method SomeMethod. / a return object / /- / Change History: / DateWho Changes Made / 2000-5-1Author1Initial creation / 2000-5-15Author2Add some code /- public object SomeMethod(object param1) 4.4声声明明 4.4.1 单单行行声声明明变变量量数数 我们推荐每行只声明一个变量，因为这样你可以在声明后

13、面写上该变量的注释，例如： int level; / indentation level int size; / size of table 请不要在同一行声明不同含义的变量，比如： int a, b; /What is a? What does b stand for? 上面的例子同样可以说明了没有意义的变量名称会让人很难理解，因此，在定义变量的时 候，我们一定要给它们一个有含义的名字。 4.4.2 初初始始化化 最好在一定义后就初始化变量，例如： string name = strObject.Name; or int val = time.Hours; 注意：如果你想要初始化对话框变量，

14、建议使用 using 声明方式 例如： using (OpenFileDialog openFileDialog = new OpenFileDialog() . 4.4.3类类和和接接口口声声明明 在声明类和接口的时候应当遵照下列规范： 方法名称和放置参数的括号”(”之间不应该有空格 类名声明之后应另起一行写作用域开始符” 作用域结束符”应当单独占一行，并与对应的开始符”处在同一缩进位置上 示例： Class MySample : MyClass, IMyInterface int myInt; public MySample(int myInt) this.myInt = myInt ;

15、void Inc() +myInt; void EmptyMethod() 4.5功功能能语语句句 4.5.1简简单单逻逻辑辑 每一行代码应当只实现一个逻辑 4.5.2if-else语语句句 if-else 应该按照这种格式书写： if(condition) DoSomething(); . else DoSomethingOther(); . 4.5.3For / Foreach 语语句句 For 循环语句格式： for(int i = 0; i 5; +i) . 或者，如果循环只有一个简单执行语句的话： for (initialization; condition; update) ; f

16、oreach 循环格式: foreach(int i in IntList) . 注意：即使循环中只有一句执行语句，我们也要求使用注意：即使循环中只有一句执行语句，我们也要求使用” 4.5.4While/do-while 语语句句 While 循环格式： while (condition) . 对于空循环可以这样写： while (condition) ; do-while 循环格式： do . while(condition); 4.5.5Switch 语语句句 switch 格式： switch (condition) case A: . break; case B: . break; d

17、efault: . break; 4.5.6Try-catch 语语句句 try-catch 格式： try . catch (Exception) 或者： try . catch (Exception e) . 或者： try . catch (Exception e) . finally . 4.6空空白白 4.6.1空空白白行行 空白行有增强可读性的作用。它们隔离了逻辑上相互独立的模块。 在下列情况中我们还可以使用双空白行： 源文件中的两个独立的逻辑片断之间 类和接口之间（但一般情况下我们还是建议一个文件一个类或接口） 下列情况中我们可以使用单空白行： 方法之间 属性之间 方法内局部变量

18、第一出声明前 方法内相对独立的逻辑之间 注意，尽量保持空白行和其他行具有同样的缩进，可以使今后插入代码能够保 持相同的缩进。 4.6.2参参数数条条件件之之间间的的空空白白 通过这些空白，可以使代码更容易被阅读，例如： TestMethod(a, b, c); 而不应该这样： TestMethod(a,b,c) 但是也不应有过多的空格，比如： TestMethod( a, b, c ); 操作符和变量或数字之间应该有空格： a = b; / dont use a=b; for (int i = 0; i 10; +i) / dont use for (int i=0; i10; +i) / o

19、r / for(int i=0;i10;+i) 4.6.3表表格格式式的的样样式式 连续的多行付值语句可以这样子写： string strName = Mr. Ed; int nValue = 5; Test aTest = Test.TestYou; 利用空格对齐所有的“=”，使代码块看起来像表格一样。 4.7命命名名规规范范 4.7.1大大写写 Pascal 风风格格 变量的首字母大写，如：Name 驼驼峰峰规规则则 除了首个单词，每个单词的首字母大写，如：TestName 大大写写风风格格 只在少于两个字母的缩写中使用大写。三个以上字母的缩写都

20、应该使用 PASCAL 风格。 4.7.2命命名名方方法法 通常我们采用匈牙利命名法来为变量命名。 匈牙利命名法通常采用变量类型的缩写作为前缀，变量含义的全拼作为后缀的方法来命 名变量。这种命名方法被广泛的采用在 windows 程序开发中，它因由一匈牙利程序员创立 而得名。 注意：好的变量命名不是突出其类型，而是突出其含义。 对于对于 UI 控件，我们强制要求缩写前缀控件，我们强制要求缩写前缀，例如： System.Windows.Forms.Button btnCancel; System.Windows.Forms.TextBox txtName; 类类命命名名 使用名词或

21、名词短语命名类。 使用 Pascal 风格. 谨慎使用缩写命名类。. 不要使用任何类前缀（如 C）. 接接口口命命名名 使用名词或名词短语命名接口.(例如 IComponent 或 IEnumberable) 使用 Pascal 风格 使用大写的 I 作为首字母，表示为接口 枚枚举举命命名名 使用 Pascal 风格 不使用前缀 使用单数名词命名 常常量量命命名名 采用有意义的单词命名 使用全部大写字母拼写 参参数数命命名名 相对变量而言，参数更注重本身的含义作为命名 使用驼峰规则命名 变变量量命命名名 作为循环中的运算子的

22、变量，更适合采用简单的命名，如 i, j, k, l, m, n 方方法法命命名名 采用动词命名，或者动词词组 使用 Pascal 风格 属属性性命命名名 使用名词或名词短语命名属性 使用 Pascal 风格 事事件件命命名名 使用 EventHandler 作为事件句柄的后缀 使用两个参数：sender 和 e 使用 Pascal 风格 使用 EventArgs 作为 Event Argument 类型名的后缀 使用进行时动词和过去式动词作为事件的名称 0 大大写写风风格格 TypeCaseNotes Class / StructPas

23、cal Casing InterfacePascal CasingStarts with I Enum valuesPascal Casing Enum typePascal Casing EventsPascal Casing Exception classPascal CasingEnd with Exception public FieldsPascal Casing MethodsPascal Casing NamespacePascal Casing PropertyPascal Casing Protected/private FieldsCamel Casing Paramete

24、rsCamel Casing 4.8开开发发习习惯惯 4.8.1可可见见性性 请避免将类变量或一个实例声明为公共类型的变量，而应该将其声明为私有变 量。 如果你确实需要公开一个类变量或者实例的话，可以使 990 用属性(Property) 来公开它。 4.8.2不不要要硬硬编编码码数数字字 也就是说，在你的逻辑代码中，不要采用数字直接参与计算，尤其是那些可能需要改变的 数字。你应该将它付值给一个常量，使用该常量参与计算。这样做得好处是，如果这个数字改 变的时候，你不必在代码中将他找出并修改，而只需修改常量的值。 public class MyMath public const double P

25、I = 3.14159. 4.9代代码码示示例例 4.9.1作作用用域域（ “”）示示例例 namespace ShowMeTheBracket public enum Test TestMe, TestYou public class TestMeClass Test test; public Test Test get return test; set test = value; void DoSomething() if (test = Test.TestMe) /.stuff gets done else /.other stuff gets done 作用域（”）应该在下列代码后另起

26、一行开始： Namespace 声明后 Class/ Interface / Struct 的声明后 Method 声明后 循环或者判断(ifelse)后 5控控件件命命名名规规范范以以及及一一般般用用法法 控件名控件名简写简写(前缀前缀)用途及说明说明用途及说明说明 Labellbl TextBoxtxt Buttonbtn LinkButtoninkbtn ImageButtonimgbtn ListBoxlst DropDownListddl DateGriddg DataListdl CheckBoxchk CheckBoxListchklst RadioButtonrdo Radio

27、ButtonListrdolst Imageimg Panelpnl Calendercal AdRotatorar Tabletab RequiredFieldValidatorrfv CompareValidatorcv RangeValidatorrv RegularExpressionValidatorrev ValidatorSummarvs CrystalReportViewerrptvew ComboBoxcbo 使用数据集直接填充下拉列表 cbo.DisplayMember = ds.Tables.Columns; cbo.ValueMember = ds.Tables.Col

28、umns; comboBox1.DataSource = ds.Tables; 注: DisplayMember: 在下列表中的显示 ValueMember: cbo.SelectedValue(相当与 Tag) DataGridViewdgv 使用它只要在代码中添加它的数据源就 OK 控件名.DataSource = 数据集中的表; dgv.SelectRows0.Cell“列名”.Value 注: SelectRows0: 表示选中的第一行 Cell“列名”: 列的单元格 Value: 单元格中的值 DataGridView 的的 Columncol GroupBoxgrp ImageLi

29、stil ListViewlv ListViewItem lv = new ListViewItem(第 1 行第 1 列); lv.Tag = 第 1 行第 1 列; listView.Items.Add(lv); lv.SubItems.AddRange(new string 子项); ListView 的的 ColumnHeadercol MenuStripms ToolStripMenuItemtsmi PictureBoxpic StatusStripss StatusLabelslbl TabControltab Tabpagetp Timertmr ToolStripts Too

30、lStripLabeltslbl ToolStripDropDownButtontsddb DomainUpDowndud TreeViewtv tvw WebBrowserwb ObjectDataSourceods FileUploadful HiddenFieldhf GridViewgv PagedDataSourcepds Repeaterrpt contextMenuStripcms选择使用右键控件属性中的 contextMenuStrip 属性 6参参考考 7附附录录 7.1XML注注释释标标记记的的使使用用 7.1.1Section 标标记记 Section 标记用于定义不同的

31、代码文档的区域。它们都是顶级标记，Block 标记、Inline 标记都应包含在某个 Section 标记的内部。（除非自定义了扩展 XSLT 转换，否则，在 Section 标记外部的 Block 标记或 Inline 标记都被忽略。） 标记标记说明说明 NDoc 扩充扩充 对某个成员可能引发的事件的说明。 “示例”，帮助类库使用者理解类型/成员使用方法的示例代码。 对某个成员可以抛出的异常的说明。 NDoc 扩充扩充 指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。 与文档引擎的“可见性”配置不符的，以 exclude 优先。 将代码文件外部的某 XML 文件中的一部分包含

32、进代码文件来。 NDoc 扩充扩充 为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载 成员的第一个成员前面书写此区域即可。 标记有两种形式: 简单的形式，直接在 overload 中写文本，这些文本被处理为“重 载列表”页面的摘要。没有备注、示例等区域。 复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。 标记标记说明说明 示例: /This method has two overloads. /This overload just says hello. public void SayHello() . /This one says hello to someone. public void SayHello(string toSomeone) . 成员的参数说明。 访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。 NDoc 扩充