C#编码规范细则.docx

1、C#编码规范细则技 术 文 件 技术文件名称：C#编码规范-细则 技术文件编号： 版 本：1.3 共 40 页(包括封面) 拟 制 审 核 会 签 标准化 批 准 中兴通讯股份有限公司质企中心IT部目 录前言 41 范围 52 术语和定义 52.1 原则 52.2 规则 52.3 建议 52.4 说明 52.5 正例 52.6 反例 53 代码布局 53.1 基本格式 53.2 对齐 73.3 空行空格 83.4 断行 94 注 释 105 命名规则 146 声明 207 表达式与语句 218 类和接口 259 附编程实例 27版本变更记录版本号拟制/修改日期拟制/修改人修改记录批准人1.02

2、004-7-15于平删去基本原则部分，在规范总则中体现；对注释部分进行修改；增加编程实例。1.12004-7-27于平修改类变量、局部变量、方法参数、命名空间的命名规则。2004-10-9陈沛增加了类编号说明;取消类头的方法属性列表要求；取消方法编号要求。1.32005-3-16韩荣华根据过程资产库架构指南调整文件名及引用陈沛注： 1）拟制、审核、会签、批准不走电子流程时，必须用钢笔或签字笔填写，不得用铅笔、圆珠笔填写，不得涂改。本模板中用“”括起来的内容包括本段，是编写指导，在最终的文档中应予以删除。其它内容应予以保留。如果某节内容无需填写，则在该节下写“无”，而不要将本节删除或不填写任何内

3、容（留白将无法判断：是本节内容无需填写还是因为疏忽而忘了填写。）前言编码规范包括总则和细则两部分。总则部分是对编码的总体性规范要求，适用于多种编码语言；细则部分是在总则的规范要求下，针对具体语言的特点而提出的规范要求。本规范是编码规范的细则部分，适用于DOTNET平台的C编程语言。编写本规范的目的是为了进一步规范C软件编程风格，提高软件源程序的可读性、可靠性和可重用性，确保在开发成员或开发团队之间的工作可以顺利交接，不必花很大的力气便能理解已编写的代码，以便继续维护和改进以前的工作，提高软件源程序的质量和可维护性，减少软件维护成本。本规范的内容包括：代码布局、注释、命名规则、声名、表达式与语句

4、、类与接口等。规范最后给出了一个编程实例供软件人员参考。本规范分成规则性和建议性两种：对于规则性规范，要求所有软件开发人员严格执行；对于建议性规范，各项目编程人员可以根据实际情况选择执行。自本规范实施之日起，以后新编写的和修改的代码均应执行本规范。1 范围 本标准规定了C#语言的编程规范，主要包括代码布局、注释、命名规则、声明、表达式与语句、类与接口等。本规范自生效之日起，对以后新编写的和修改的代码有约束力。2 术语和定义下列术语和定义适用于本标准。2.1 原则编程时应该坚持的指导思想。2.2 规则编程时必须遵守的约定。2.3 建议编程时必须加以考虑的约定。2.4 说明对此规则或建议的必要的解

5、释。2.5 正例对此规则或建议给出的正确例子。2.6 反例对此规则或建议给出的反面例子。3 代码布局代码布局的目的是显示出程序良好的逻辑结构，提高程序的准确性、连续性、可读性、可维护性。更重要的是，统一的程序布局和编程风格，有助于提高整个项目的开发质量，提高开发效率，降低开发成本。同时，对于普通程序员来说，养成良好的编程习惯有助于提高自己的编程水平，提高编程效率。因此，统一的、良好的程序布局和编程风格不仅仅是个人主观美学上的或是形式上的问题，而且会涉及到产品质量，涉及到个人编程能力的提高，必须要引起重视。3.1 基本格式【规则3-1-1】源代码文件（.cs）的布局顺序是：using语句、命名空

6、间、类。正例： using System;namespace ZTE.xxxpublic class Sample【规则3-1-2】遵循统一的布局顺序来书写using语句，不同类别的using语句之间用空行分隔。说明：using命名空间语句的排列顺序为System开头的命名空间在最前面，接下来是引自外部的命名空间，再接下来是应用程序自身的命名空间，即using 中标准的命名空间要在本地的命名空间之前，而且按照字母顺序排列。正例:using System; / .Net自身的using System.Data;using FarPoint.Win.Spread; /第三方的using ZTE.D

7、SS.Public; /程序自身的【规则3-1-3】if、else、else if、for、while、do等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加 。说明：这样可以防止书写失误，也易于阅读。正例：if (varible1 varible2) varible1 = varible2;反例：下面的代码执行语句紧跟if的条件之后，而且没有加，违反规则。if (varible1 varible2) varible1 = varible2; 建议3-1-4源程序中关系较为紧密的代码应尽可能相邻。说明：这样便于程序阅读和查找。正例：iLength = 10;iWidth = 5;

8、/ 矩形的长与宽关系较密切，放在一起。StrCaption = “Test”;反例：iLength = 10;strCaption = “Test”; iWidth = 5;3.2 对齐【规则3-2-1】 禁止使用TAB键，必须使用空格进行缩进。缩进为4个空格。说明：消除不同编辑器对TAB处理的差异，有的代码编辑器可以设置用空格代替TAB键。【规则3-2-2】程序的分界符和应独占一行并且位于同一列，同时与引用它们的语句左对齐。 之内的代码块使用缩进规则对齐。说明：这样使代码便于阅读，并且方便注释。do while语句和结构的类型化时可以例外，while条件和结构名可与 在同一行。正例：void

9、 Function(int intVar) / 独占一行并与引用语句左对齐。while (condition)DoSomething(); / 与 缩进4格反例：void Function(int intVar)while (condition)DoSomething();【建议3-2-1】相关的赋值语句等号对齐。正例：tPDBRes.wHead = 0;tPDBRes.wTail = wMaxNumOfPDB - 1;tPDBRes.wFree = wMaxNumOfPDB;tPDBRes.wAddress = wPDBAddr;tPDBRes.wSize = wPDBSize;3.3 空行

10、空格【规则3-3-1】不同逻辑程序块之间要使用空行分隔。说明：空行起着分隔程序段落的作用。适当的空行可以使程序的布局更加清晰。正例：void Hey(void)Hey实现代码/ 空一行void Ack(void)Ack实现代码反例：void Hey(void) Hey实现代码void Ack(void)Ack实现代码/ 两个函数的实现是两个逻辑程序块，应该用空行加以分隔。【规则3-3-2】一元操作符如“!”、“”、“+”、“-”、“*”、“&”等前后不加空格。“”、“.”这类操作符前后不加空格。正例：!bValueiValue+iCount&fSumaiNumberi = 5;tBox.dWi

11、dth 【规则3-3-3】多元运算符和它们的操作数之间至少需要一个空格。正例：fValue = fOldValue;fTotal + fValueiNumber += 2;【规则3-3-4】关键字之后要留空格。说明：if、for、while等关键字之后应留一个空格再跟左括号(，以突出关键字。【规则3-3-5】函数名之后不要留空格。说明：函数名后紧跟左括号(，以与关键字区别。【规则3-3-6】(向后紧跟，)、,、;向前紧跟，紧跟处不留空格。,之后要留空格。;不是行结束符号时其后要留空格。正例：例子中的 凵 代表空格。 for凵(i凵=凵0;凵i凵凵MAX_BSC_NUM;凵i+)DoSometh

12、ing(iWidth,凵iHeight);3.4 断行【规则3-4-1】长表达式（超过120列）要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要进行适当的缩进，使排版整齐。说明：条件表达式的续行在第一个条件处对齐。for循环语句的续行在初始化条件语句处对齐。函数调用和函数声明的续行在第一个参数处对齐。赋值语句的续行应在赋值号处对齐。正例：if (iFormat = CH_A_Format_M) & (iOfficeType = CH_BSC_M) / 条件表达式的续行在第一个条件处对齐 DoSomething();for (long_initializati

13、on_statement;long_condiction_statement; / for循环语句续行在初始化条件语句处对齐long_update_statement) DoSomething();/ 函数声明的续行在第一个参数处对齐BYTE ReportStatusCheckPara(BYTE bytCallNo, BYTE bytStatusReportNo);/ 赋值语句的续行应在赋值号处对齐fltTotalBill = fltTotalBill + fltarrCustomerPurchasesintID+ fltSalesTax(fltarrCustomerPurchasesintI

14、D);【规则3-4-2】函数声明时，类型与名称不允许分行书写。正例：double CalcArea(double dblWidth, double dblHeight);反例：double CalcArea(double dblWidth, double dblHeight);4 注 释注释有助于理解代码，有效的注释是指在代码的功能、意图层次上进行注释，提供有用、额外的信息，而不是代码表面意义的简单重复。【规则4-1】类、方法、属性的注释采用XML文档格式注释。文件头部、代码间多行注释为“/* */”，单行注释采用“/ ”。正例：public class Sample /数据成员 (单行注释)

15、private int mProperty1; / (XML注释) / 示例属性 / public int Property1 get return mProperty1; /* set ( 多行注释) mProperty1 = value; */ 【规则4-2】注释符与注释内容之间要用一个空格进行分隔。正例：/* 注释内容 */ 注释内容反例： /*注释内容*/注释内容【规则4-3】类、接口头部应进行XML注释。说明：注释必须列出：类、接口编号、名称、内容摘要等。类编号由功能模块编号和类名两部分组成，中间用“_”隔开，功能模块编号使用该类所在的功能模块的编号，类名用类的名称。例如：M01_E

16、mployee。正例：/ / 类编号：/ 类名称：/ 内容摘要: / 【规则4-4】公共方法前面应进行XML注释。 说明：注释必须列出：主要功能、参数类型、输入参数、返回值、调用的前置条件和后置条件、异常说明、关键算法、可见性决策等。【规则4-5】包含在 中代码块的结束处应加注释，便于阅读。特别是多分支、多重嵌套的条件语句或循环语句。说明：此时注释可以用英文，方便查找对应的语句。正例： void Main（）if () while () /* end of while () */ / 指明该条while语句结束 /* end of if () */ / 指明是哪条语句结束 /* end of

17、void main（）*/ / 指明函数的结束【规则4-6】注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。说明：在使用缩写时或之前，应对缩写进行必要的说明。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。正例： 如下书写比较结构清晰/* 获得子系统索引 */iSubSysIndex = aDataiIndex.iSysIndex;/* 代码段1注释 */ 代码段1 /* 代码段2注释 */ 代码段2 反例1：如

18、下例子注释与描述的代码相隔太远。/* 获得子系统索引 */iSubSysIndex = aDataiIndex.iSysIndex;反例2：如下例子注释不应放在所描述的代码下面。iSubSysIndex = aDataiIndex.iSysIndex; /* 获得子系统索引 */反例3：如下例子，显得代码与注释过于紧凑。/* 代码段1注释 */ 代码段1 /* 代码段2注释 */ 代码段2 【规则4-7】注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。正例： 如下注释结构比较清晰int DoSomething(void)/* 代码段1注释 */ 代码段1 /*

19、代码段2注释 */ 代码段2 反例：如下例子，排版不整齐，阅读不方便；int DoSomething(void)/* 代码段1注释 */ 代码段1 /* 代码段2注释 */ 代码段2 【规则4-8】对分支语句（条件分支、循环语句等）必须编写注释。说明：这些语句往往是程序实现某一特殊功能的关键，对于维护人员来说，良好的注释有助于更好的理解程序，有时甚至优于看设计文档。建议4-1通过对函数或过程、变量、结构等正确的命名以及合理地组织代码结构，使代码成为自注释的。说明：清晰准确的函数、变量命名，可增加代码的可读性。建议4-2尽量避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时，应对缩写进行

20、必要的说明。5 命名规则好的命名规则能极大地增加可读性和可维护性。同时，对于一个有上百个人共同完成的大项目来说，统一命名约定也是一项必不可少的内容。本章对程序中的所有标识符（包括命名空间、变量名、常量名、控件名、参数名、属性名、方法名、类名、接口等）的命名做出约定。三种命名规范说明：Pascal规范：第1个字符大写，目标名中的每个单词的第1个字母也大写，比如InvoiceNumber或者PrintInvoice。其他的所有字符都小写。Camel规范：第1个字符不大写，但目标名中的每个单词的第1个字母大写，比如，invoiceNumber。其他的所有字符都小写。匈牙利规范：在目标名中加入表示类型

21、的前缀，前缀小写，如strName。【规则5-1】标识符要采用英文单词或其组合，便于记忆和阅读，切忌使用汉语拼音来命名。说明：标识符应当直观且可以拼读，可望文知义，避免使人产生误解。程序中的英文单词一般不要太复杂，用词应当准确。【规则5-2】标识符只能由26个英文字母，10个数字，及下划线的一个子集来组成，并严格禁止使用连续的下划线，下划线也不能出现在标识符头或结尾（预编译开关和利用工具生成的代码除外）；数字也不能出现在标识符的头部。说明：这样做的目的是为了使程序易读。因为 variable_name 和 variable_name 很难区分，下划线符号_若出现在标识符头或结尾，容易与不带下划

22、线_的标识符混淆。【规则5-3】标识符的命名应当符合“min-length & max-information”原则。说明：较短的单词可通过去掉“元音”形成缩写，较长的单词可取单词的头几个字母形成缩写，一些单词有大家公认的缩写，常用单词的缩写必须统一。协议中的单词的缩写与协议保持一致。对于某个系统使用的专用缩写应该在某处做统一说明。在使用缩写时，应该按着专业术语的要求大小写，例如，System.IO，而不是 System.Io。正例：如下单词的缩写能够被大家认可： temp 可缩写为 tmp ； flag 可缩写为 flg ； statistic 可缩写为 stat ； increment 可

23、缩写为 inc ； message 可缩写为 msg ；规定的常用缩写如下： 常用词缩写ArgumentArgBufferBufClearClrClockClkCompareCmpConfigurationCfgContextCtxDelayDlyDeviceDevDisableDisDisplayDispEnableEnErrorErrFunctionFnctHexadecimalHexHigh Priority TaskHPTI/O SystemIOSInitializeInitMailboxMboxManagerMgrMaximumMaxMessageMsgMinimumMinMulti

24、plexMuxOperating SystemOSOverflowOvfParameterParamPointerPtrPreviousPrevPriorityPrioReadRdReadyRdyRegisterRegScheduleSchedSemaphoreSemStackStkSynchronizeSyncTimerTmrTriggerTrigWriteWr【规则5-4】采用应用领域相关的术语来命名。说明：软件开发人员应注意软件用户的一些约定术语，不应当随意的创造术语，这会降低软件的易用性。【规则5-5】程序中不要出现仅靠大小写区分的相似的标识符。【规则5-6】用正确的反义词组命名具有互

25、斥意义的变量或相反动作的函数等。说明：下面是一些在软件中常用的反义词组。 add/remove ； begin/end ； create/destroy ； insert/delete ； first/last ； get/release ； increment/decrement ； put/get ； add/delete ； lock/unlock ； open/close ； min/max ； old/new ； start/stop ； next/previous ； source/target ； show/hide ； send/receive ；source/destinat

26、ion ； cut/paste ； up/down【规则5-7】常量名都要使用大写字母, 用下划线 _ 分割单词。正例：如 DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE 等等。【规则5-8】一般变量名不得取单个字符（如i、j、k等）作为变量名，局部循环变量除外。说明：变量，尤其是局部变量，如果用单个字符表示，很容易出错（如l误写成1）,而编译时又检查不出，则有可能增加排错时间。过长的变量名会增加工作量，会使程序的逻辑流程变得模糊，给修改带来困难，所以应当选择精炼、意义明确的名字，才能简化程序语句，改善对程序功能的理解。【规则5-9】类方法的局部变量命名采用Camel规范或

27、匈牙利规范。说明：常用变量类型前缀列表如下：int ： intflt ： floatdbl ： doublechr ： charlng ： longsht ： shortbl ： boolush ： ushort uln ： ulongarr ： arraystr ： string【规则5-10】类成员变量名应由前缀+变量名主体组成，变量名的主体应当使用“名词”或者“形容词名词”，且首字母必须大写。说明：前缀为m或_，一般是对应属性的私有变量是m开头的，对应聚合组合依赖等关系的是_开头。正例：private static string mPersonName; private static s

28、tring _PersonName; private string mPersonName;private string _PersonName;【规则5-11】控件命名应采用完整的英文描述符命名，名字的前缀是控件类型名缩写，符合匈牙利命名规范。说明：控件缩写LabellblTextBoxtxtCheckBoxchkButtonbtnListBoxlstDropDownListddlstLinkButton lbtnImageButton ibtnRadioButtonList rblstCheckBoxList chlstDataGrid dgDataList dlHyperLink hlnkRepeater rpImage img等等【规则5-12】Enum 类型和值命名采用Pascal规范，不要在 Enum 类型名称上使用 Enum 后缀。【规则5-13】类方法的参数名命名采用Camel规范或匈牙利规范