项目开发规范.doc

项目开发规范1 引言1.1 概述本项目编码规范主要针对目前主流的DotNet和JAVA开发管理应用系统中编码提供参考和依据，该规范结合本人在项目中的实践经验同时参考一些软件行业编码规则编写而成,以此作为项目开发标准,规范。本编码规范不但从代码组织，外观，注释，命名，语句等方面制定规范，而且还考虑通过编码保证和提升系统的性能。1.2 编写目的u 使编写的代码在整个项目中具有规范、标准，统一的风格。u 编码规范是公司软件系统质量控制的重要内容，标准、规范的代码可以保证和提高软件系统性能。u 方便代码的交流，提高编码的效率，符合大众习惯。u 使代码更美观、逻辑清晰，可读性强（便于阅读和理解），可移植性强，便于系统后期维护。1.3 读者对象u 公司项目决策管理层u 项目负责人及项目管理人员u 系统分析，设计人员u 程序开发人员及测试人员u 软件质量管理人员1.4 背景在项目开发中的编码规范是软件开发基本必须的工作，同时也是软件质量的重要保证，做为项管理和开发人员具有良好、规范的编码习惯是基本要求。但编码规范在软件开发过程中经常不被重视，经常见到的是没有编码规范，有编码规范但没有真正很好地按编码规范进行控制。针对该问题我们出此规范，作为我们开发过程标准规范。1.5 适应范围u 适用于企业所有基于.NET平台的软件采用C#开发的软件系统。u JAVA语言及平台开的软件产品。u ORACLE数据库PL/SQL语句。u 程序中JavaScript代码。1.6 定义1.6.1 Pascal 命名约定将标识符的首字母和后面连接的每个单词的首字母都大写即每个单词的首字母大写。例如：BackColor。1.6.2 Camel 命名约定标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColor。1.7 参考资料暂无。1.8 文档标志u 编 写 者：张洪波 u 参与人员：张洪波u 编写时间：2010-05-13u 版本：Ver1.0.01.9 文档总体说明这里针对一些编码中大的原则及公共的地方在这里统一进行描述和说明：u Pascal和Camel规则在C#，JAVA，JS中应用 涉及到公共接口部分如：接口，类中方法均采用Pascal规则。 涉及到变量一般采用Camel规则u ORACLE中对象如表名，字段名，函数名，存储过程名，序列，包均全部大写。2 C#编码规范2.1 程序组织结构Web的目录结构一般组织如下：编号文件描述备注10WebUI用户界面层1001UserControls 用户控件1002UICommon UI公共部分1003Test 测试页面1004Temp 临时文件夹1005Include Include文件夹100501JsFile JS脚本100502CssFile CSS样式文件100503Image 用户图片100504Images 系统图片1006DVLP 辅助开发部分对项目辅助，辅助系统开发，实施和维护，原则上删除对系统没有影响，但一般情况下会留在系统中。1007bin DLL文件1008BaseData 基础数据1009PurchaseManage 采购管理1010 20BnsLog业务规则层2001BaseData 基础数据2002PurchaseManage 采购管理2003 30数据访问层3001BaseData 基础数据3002PurchaseManage 采购管理3003 40DataEntity实体层4001BaseData 基础数据4002PurchaseManage 采购管理4003 50DataBase数据库层60CommClass通用层2.2 文件组织规范2.2.1 文件命名u 文件名遵从Pascal命名法，无特殊情况，扩展名小写。u 使用统一而又通用的文件扩展名： C# 类 .csu 文件命名尽量使用有意义的名子命名如：DataBase.cs,表示是对数据库操作的类。禁止使用没有意义的文件名：如ABC.cs2.2.2 文件代码行数u 避免使用大文件。如果一个文件里的代码超过300400行，应该考虑将代码分开到不同类中。2.2.3 文件注释文件注释格式如下：/ */ * 版权说明：Copyright (C) 2004 *公司版权所有 */ * 功能说明：对一个算术表达式进行计算并返回结果 */ * 创建标志：张洪波 2007年月日创建 */ * 修改标志： */ * 标志编号：O01 张洪波2007年11月01日 */ * 标志描述：对诸如：（-5）的计算不正确进行修正 */ * */ * 标志编号：O02 张洪波2007年11月17日 */ * 标志描述：在构造函数对精度进行默认设置 */ * */ * 标志编号：O03 张洪波2008年01月01日 */ * 标志描述：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx */ * xxxxxxxxxxxxxxxxxxxxxxxxxxx */ * 附注说明：用动态数组来仿真实现堆栈 */ * 注：如果在一天内进行了多次修改，只需记录一次修改标志,文件功能说明只进行简要描述，详细的描述在文件内部。2.2.4 文件内容组织针对文件内容组织则相对灵活些,这里我们针对DotNet的CS文件中平时经常使用的一种方式供大家参考,该文件内容一般分为以下几个部分:(1) 文件注释即上面的文件注释(2) 类中控件及引用对象变量页面中的服务器控件,以及为类提供服务的对象如业务规则对象,实体对象等,这里实质均为类的数据成员,为了更加清晰也可以将这里分为两个部分为:控件和类使用的对象两个部分。(3) 类的属性类的属性是类针对数据成员（当然也有其它）提供对外界的接口（当然接口也可以对内甚至不一定为公有）。(4) 构造函数构造函数一般是缺省的（注意还是有的，不过是没有显式地写出来而已），但如果涉及到页类的继承则通常会有。(5) 页面初始化即Web 窗体设计器生成的代码OnInit()，是页面的初始化函数，一般情况下我们不需要在里面实现代码，但有时为了需要我们会在里面实现一些功能。(6) 页面载入即Page_Load()，我们经常在这里实现我们自己的处理过程。(7) 用户触发事件这里是服务器控件（包括运行的服务器端的客户端控件）的用户触发事件。(8) AJAX处理过程这里是前台AJAX调用的方法。(9) 类内部服务的方法针对以上从类的属性到AJAX甚至类内部服务的方法中一些处理实现的子过程，专门写到这里为了使上面的逻辑更加清晰、分明。针对以上几个部分用区域分隔开来即用#region和#endregion进行分为几个区域。2.3 命名及使用规范名称应该说明“什么”而不是“如何”。通过避免使用公开基础实现（它们会发生改变）的名称，可以保留简化复杂性的抽象层。例如可以使用 GetNextStudent()，而不是 GetNextArrayElement()。使名中遵循以下命名原则：选择正确名称时的困难可能表明需要进一步分析或定义项的目的。使名称足够长以便有一定的意义，并且足够短以避免冗长。唯一名称在编程上仅用于将各项区分开。表现力强的名称是为了帮助人们阅读；因此，提供人们可以理解的名称是有意义的。不过，请确保选择的名称符合适用语言的规则和标准。以下几点是推荐的命名方法。u 避免容易被主观解释的难懂的名称，如方面名 AnalyzeThis()，或者属性名 xxK8。这样的名称会导致多义性。 u 对于本来说是缩这写的形式，应该仍采用缩写形式如：System.IO，中IO表示输入输出，不应该写为Io或oI等形式。u 避免使用和以下关键字冲突的标识符AddHandlerAddressOfAliasAndAnsiAsAssemblyAutoBaseBooleanByRefByteByValCallCaseCatchCBoolCByteCcharCDateCDecCDblCharCintClassCLngCObjConstCshortCSngCStrCTypeDateDecimalDeclareDefaultDelegateDimDoDoubleEachElseElseIfEndEnumEraseErrorEventExitExternalSourceFALSEFinalizeFinally FloatForFriendFunctionGetGetTypeGotoHandlesIfImplementsImportsInInheritsIntegerInterfaceIsLetLibLikeLongLoop MeModModuleMustInheritMustOverrideMyBaseMyClassNamespaceNewNextNotNothingNotInheritableNotOverridableObjectOnOptionOptionalOrOverloadsOverridableOverridesParamArrayPreservePrivatePropertyProtectedPublicRaiseEventReadOnlyReDimRegionREMRemoveHandlerResumeReturnSelectSetShadowsSharedShortSingleStaticStepStopStringStructureSubSyncLockThenThrowToTRUETryTypeOfUnicodeUntilvolatileWhenWhileWithWithEventsWriteOnlyXorEvalextendsinstanceofpackagevar2.3.1 常量的命名及使用规则 常量命名规则u 所有单词大写，多个单词之间用 _ 隔开。 如public const string PAGE_TITLE = Welcome; 常量使用规则可能的情况下，尽量不要使用原义数字或原义字符串，如For i = 1 To 7。而是使用命名常数，如 For i = 1 To NUM_DAYS_IN_WEEK 以便于维护和理解。2.3.2 变量命名及使用规则 变量命名规则u 采用Camel命名规则。u 不要对字段名使用匈牙利语表示法。u 采用数据类型+变量名命名规则：该规则适宜于方法中参数（方法中的参数实质也是一种局部变量），块中局部变量等如：int nCount;/为一个整型计数器变量。常用变量类型缩写如下表：变量类型描述习惯变量类型适应变量类型缩写备注整型intSystem.Int16,System.Int32,System.Int64,System.UInt16,System.UInt32,System.UInt64,inti或n建议采用n,因为接口也是以i开头的字符串stringSystem.Stringstr建议采用str(但也可使用s)小数doubleSystem.Double,System.Decima,float,doubled或fd 表示双精度小数,f表示浮点型数据表DataTableSystem.Data.DataTabledt数据集DataSetSystem.Data.DataSetds日期System.DateTimedtmu 变量命名时尽量避免仅使用DotNe已使用或易混淆的字符串进行命名(这些字符串与保留字不同,采用这些字符串进行命名是合法的,而采用保留字进行命名则是不合法的)如:System.DateTime data = new DateTime(2006,7,12);该命名虽然合法但不妥,原因是System.Data中已使用该命名,这时我们可以加上表示类型以及其它字母为其起一个有意义的名字:System.DateTime dtmValidDate = new DateTime(2006,7,12);u 只要合适，在变量名的末尾或开头加计算限定符（Avg、Sum、Min、Max、Index）。u 在变量名中使用互补对，如 min/max、begin/end 和 open/close。 u 布尔变量名应该包含 Is或者bl，这意味着 Yes/No 或 True/False 值，如 fileIsFound或isSameValueu 在命名状态变量时，避免使用诸如 Flag 的术语。状态变量不同于布尔变量的地方是它可以具有两个以上的可能值。不是使用 documentFlag，而是使用更具描述性的名称，如 documentFormatType。 （此项只供参考）u 即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。u 变量建议置于块的开始处，不要总是在第一次使用它们的地方做声明。在变量声明时就对其做初始化(值类型初始化为0,引用类型初始化为NULL),在声明变量时应该按以下顺序进行声明:枚举型,整形,小数,时间日期,字符串,其它系统对象类型,用户自定义的对象。u 尽量避免使用缩写，除非在开发人员一般都能理解时使用缩写或该缩写已约定成形。例如：string strUrl;其中strUrl表示是是网址字符串变量u 集合是一组组合在一起的类似的类型化对象，如哈希表、查询、堆栈、字典和列表，集合的命名建议用复数。例如：protected IDictionary dictOleTableColumns;u 如果变量是返回值,那么命名时用类型+retValue如方法返回一个字符串值那么其命名采用strRetValue。 变量使用规则u 不要在方法间共享成员变量，如果在几个方法间共享一个成员变量，那就很难知道是哪个方法在什么时候修改了它的值。u 必要时使用enum 。别用数字或字符串来指示离散值。u 可使用缩写使名称长度适中，通常，多于 32 个字符的变量名在低分辨率的监视器上难以阅读。同时，请确保缩写在整个应用程序中保持一致。2.3.3 参数的命名及使用规则 参数命名规则u 方法中的参数采用Camel命名规则，因为参数在某种程度上也可以说是局部变量。u 使用描述性参数名称参数名称应当具有足够的描述性，以便参数的名称及其类型可用于在大多数情况下确定它的含义。例如，提供上下文相关帮助的可视化设计工具会按开发人员键入的实际内容显示方法参数。在这种情况下，方法参数名称的表述必须清楚明白，开发人员才能提供正确的参数。 使用描述参数的含义的名称，而不要使用描述参数的类型的名称。开发工具将提供有关参数的类型的有意义的信息。因此，通过描述意义，可以更好地使用参数的名称。少用基于类型的参数名称，仅在适合使用它们的地方使用它们。 u 不要使用保留的参数保留的参数是专用参数，如果需要，可以在未来的版本中公开它们。相反，如果在类库的未来版本中需要更多的数据，请为方法添加新的重载。 u 不要给参数名称加匈牙利语类型表示法的前缀。u 参数与对之对的数据成员命名一般一样，虽然这样看起来怪怪的，但这是正确，标准的命名方法。 参数使用规则2.3.4 数据成员命名及使用规则 数据成员命名规则u 用名词或名词短语命名数据成员，可以采用将数据成员第一个字母变为大写来为数据成员对应的属性进行命名。u 私有的和受保护的一律采用Camel 命名规则，公有的一律采用Pascal命名规则；例如：public class Adder private double dAddend; private double dAugend; public Adder() this.dAddend = 78.00; this.dAugend = 100000.00; public double AddProcess() int dResult = 0; dResult = this.dAddend + this.dAugend; return dResult; u 在面向对象的语言中，在类属性的名称中包含类名是多余的，如 Book.BookTitle。而是应该使用 Book.Title。 数据成员使用规则u 别把成员变量声明为 public。具体声明为受保护或私有根据其具体需要而定。一般来讲尽量限制其可见性，比如能定义为私有的就不要定义为受保护的。2.3.5 方法命名及使用规则 方法的命名规则u 在类中方法一律采用Pascal命名规则；u 使用动词或动词短语命名方法。u 在方法名与其后的左括号间没有任何空格。u 左花括号 “” 出现在声明的下行并与之对齐，单独成行。u 方法间用一个空行隔开。u 方法名需能看出它作什么。u 别使用会引起误解的名字。如果名字一目了然，就无需用文档来解释方法的功能了。 方法的使用规则u 避免写太长的方法。一个典型的方法代码在125行之间。如果一个方法发代码超过25行，应该考虑将其分解为不同的方法。u 一个方法只完成一个任务。不要把多个任务组合到一个方法中，即使那些任务非常小。u 出现任何问题给用户一个友好的提示。u 如果需要的配置文件找不到，应用程序需能自己创建使用默认值的一份。u 如果在配置文件中发现错误值，应用程序要抛出错误，给出提示消息告诉用户正确值。u 错误消息需能帮助用户解决问题。永远别用象“应用程序出错”，“发现一个错误”等错误消息。而应给出象“更新数据库失败，请确保登陆id和密码正确。” 的具体消息。显示错误消息时，除了说哪里错了，还应提示用户如何解决问题。不要用象“更新数据库失败。”这样的，要提示用户怎么做：“更新数据库失败，请确保登陆id和密码正确。” u 显示给用户的消息要简短而友好。但要把所有可能的信息都记录下来，以助诊断问题。u 尽量用公共过程或子程序去代替重复的功能代码段。即如果代码一多个地方重复使用，则需要考虑将它们封装起来，以供公共使用。2.3.6 类的命名及使用规则 类的命名规则u 采用Pascal命名规则例如：public class EQApplication/类体内容u 用名词或名词短语命名类， 名字可以有两个或三个单词组成，但通常不应多于三个。u 使用全称避免缩写，除非缩写已是一种公认的约定或除非它是众所周知的，如URL、HTML u 不要使用类型前缀，如在类名称上对类使用 C 前缀。例如，使用类名称 FileStream，而不是 CFileStream。 u 不要使用下划线字符 (_)。 u 有时候需要提供以字母 I 开始的类名称，虽然该类不是接口。只要 I 是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称 IdentityStore 是适当的。u 在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如，ApplicationException 对于从名为 Exception 的类派生的类是适当的名称，原因ApplicationException 是一种Exception。u 对于异常类是以 Exception 后缀结尾u 请在应用该规则时进行合理的判断。例如，Button 对于从 Control 派生的类是适当的名称。尽管按钮是一种控件，但是将 Control 作为类名称的一部分将使名称不必要地加长。u 避免使用与常用的 .NET 框架命名空间重复的类名称。例如，不要将以下任何名称用作类名称。例如：System、Collections、Forms 或 UI。u 在WebService的类前加WS标志public class WsTextBox public void DataBind() u 自定义的属性以Attribute结尾public class AuthorAttribute : Attributeu 自定义的异常以Exception结尾public class AppException : Exception 类的使用规则u 可以编写自己的异常类。自定义异常不应从基类System.Exception派生，而要继承于IApplicationException。2.3.7 界面控件命名及使用规则 界面控件命名规则u 使用控件类名作为前缀，并且首字母小写，这样在编辑界面，可以方便查找控件，分类控件。u 对界面上任何一个控件无论是否可见（不可见的如占位符控件等）均需进行命名。u 界面控件命名采用：控件名简写 + ”_” + 英文描述，英文描述首字母大写u 不允许在控件中采用没有任何意义的数字和字母来区分，例如一页面中有两个报表打印功能，btnRptPrint1, btnReportPrint2，正确的命名为：btnHtmlRptPrint,btnCommRptPrint来分别表示它们是采用HTML方式打印的报表和通用方式打印的报表。u 常用控件命名示例：控件名简写控件名简写LabellblTextBoxtxtButtonbtnLinkButtonlnkbtnImageButton imgbtnDropDownList ddlListBoxltbDataGriddgDataListdlCheckBoxchkCheckBoxList chk RadioButtonrdbtnRadioButtonListrdbtnImageimgPanelpnlTabletb 界面控件使用规则2.3.8 ADO对象命名及使用规则 ADO对象命名规则类型前缀ConnectioncnnCommandcmdParameterparDataAdapterdaDataReaderdrdDataSetdsDataTabledtDataRowdrDataColumndcDataViewdvDataRelationdrel ADO对象使用规则2.3.9 枚举命名及使用规则 枚举命名规则u 对于 Enum 类型和值名称使用 Pascal 大小写。 u 少用缩写。 u 不要在 Enum 类型名称上使用 Enum 后缀。 u 对大多数 Enum 类型使用单数名称，但是对作为位域的 Enum 类型使用复数名称。 u 总是将 FlagsAttribute 添加到位域 Enum 类型。u 枚举命名举例： enum Days Saturday, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday ;enum BoilingPoints Celcius = 100, Fahrenheit = 212 ;enum Colors Red = 1, Green = 2, Blue = 4, Yellow = 8 ; 枚举使用规则2.3.10 接口的命名及使用规则 接口命名规则u 接口采用Pascal命名规则u 总是以 I 前缀（但以I开头的不一定都是接口），在定义类/接口对（其中类是接口的标准实现）时使用相似的名称。两个名称的区别应该只是接口名称上有字母 I 前缀。 u 用名词或名词短语，或者描述行为的形容词命名接口。例如，接口名称 IComponent 。u 使用描述性名词。接口名称 ICustomAttributeProvider 使用名词短语。名称 IPersistable 使用形容词。 u 尽量少用缩写。 u 不要使用下划线字符 (_)。 u 举例：public interface IDataBase 接口使用规则2.3.11 事件命名及使用规则 事件命名规则u 采用Pascal命名规则，不要使用匈牙利语表示法。u 对事件处理程序名称使用 EventHandler 后缀u 用 EventArgs 后缀命名事件参数类。u 指定两个名为 sender 和 e 的参数。sender 参数表示引发事件的对象。sender 参数始终是 object 类型的，即使在可以使用更为特定的类型时也如此。与事件相关联的状态封装在名为 e 的事件类的实例中。对 e 参数类型使用适当而特定的事件类。 u 考虑用动词命名事件。例如，命名正确的事件名称包括 Clicked、Painting 和 DroppedDown。u 命名事件名时，需要有之前和之后的时态概念，使用动名词（动词的“ing”形式）创建表示事件前的概念的事件名称，用过去式表示事件后。例如，可以取消的 Close 事件应当具有 Closing 事件和 Closed 事件。不要使用 BeforeXxx/AfterXxx 命名模式。 u 不要在类型的事件声明上使用前缀或者后缀。例如，使用 Close，而不要使用 OnClose。 u 通常情况下，对于可以在派生类中重写的事件，应在类型上提供一个受保护的方法（称为 OnXxx）。此方法只应具有事件参数 e，因为发送方总是类型的实例。 u 以下示例阐释具有适当名称和参数的事件处理程序。u 示例如下：C#public delegate void MouseEventHandler(object sender, MouseEventArgs e);以下示例阐释正确命名的事件参数类。C#public class MouseEventArgs : EventArgs int nX; int nY; public MouseEventArgs(int nX, int nY) this.nX = nX; this.nYy = nY; public int nX get return nX; public int nY get return nY; 事件使用规则2.3.12 命名空间命名及使用规则 命名空间命名规则u 命名命名空间时的一般性规则是使用项目名称，层名称，模块名称，如仓储管理系统中的采购管理，WMIS.BnsLog.PurchaseManage 。u 命名空间使用Pascal大小写，用逗号分隔开。u 命名空间和类不能使用同样的名字，即使它们不在同一个空间下。有一个类被命名为CommBns后，就不要再使用CommBns作为一个名称空间名。u 把引用的系统的namespace和自定义或第三方的分开。 命名空间使用规则u 命名空间中的”.”不要系统中的”.”混在一起,在命名空间中不要使用字符”.”,如WMS.ERP.BaseData,这里的WMIS.ERP.本身就是一个命名空间,则这样命名是不合适的,这样应该命名为 WMSERP.BaseData.2.4 代码外观2.4.1 列宽u 每行长度尽量避免超过屏幕宽度，一般以80个字符以内为宜，代码列宽不最宽不超过110字符。一般以出现滚动条为宜。2.4.2 换行u 当表达式超出或即将超出规定的列宽，遵循以下规则进行换行：在逗号后换行；在操作符前换行；规则1优先于规则2；u 当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。u 如果一个方法有参数过多，应该换行并且参数上下要对齐，每行参数个数需一致，一般每行3-5个参数为宜。 2.4.3 缩进 u 缩进应该是每行一个Tab(4个空格)，应该在 Visual Studio.Net设置：工具-选项-文本编辑器-C#-制表符-插入空格。2.4.4 空行u 空行是为了将逻辑上相关联的代码分块，以便提高代码的可阅读性。 在以下情况下使用两个空行：接口和类的定义之间；枚举和类的定义之间；类与类的定义之间。 u 在以下情况下使用一个空行：类注释前面，类注释与命名空间声明之间，方法与方法、属性与属性之间；方法中变量声明与语句之间；方法中不同的逻辑块之间（即用一个空行来分开代码的逻辑分组，同时可以辅以注释说明）；方法中的返回语句与其他的语句之间；属性与方法、属性与字段、方法与字段之间；注释与它注释的语句间不空行，但与其他的语句间空一行。2.4.5 空格u 在以下情况中要使用到空格：关键字和左括符 “(” 应该用空格隔开。如while (true)；，但在方法名和左括符 “(” 之间不要使用空格，这样有助于辨认代码中的方法调用与关键字。 u 多个参数用逗号隔开，每个逗号后都应加一个空格。u 除了 .和+,- - 之外，所有的二元操作符都应用空格与它们的操作数隔开, 这样做时不会改变代码的意图却可以使代码容易阅读。一元操作符、+及-与操作数间不需要空格。如 a = (a + b) / (c * d); while (d + = s +) N +; PrintSize(“size is “ + size + “n”);u 语句中的表达式，参数之间用空格隔开。如for (int nIndex = 0; nIndex 20; nIndex +)表达式参数也可以不按空格分离开来，但在一个模块内需要统一，一致，如下面的代码:for(int nIndex = 0;nIndex 20;nIndex +)以上两种写法均可，但我们推荐第二种。2.4.6 括号 - ()u 左括号“)”不要紧靠关键字，中间用一个空格隔开。u 左括号“(”与方法名之间不要添加任何空格。u 没有必要的话不要在返回语句中使用()。如u 示例： if (condition) Array.Remove(1) return 1 2.4.7 花括号 - u 左花括号 “” 放于关键字或方法名的下一行并与之对齐。如 if (condition) public int Add(int x, int y) u 左花括号 “” 要与相应的右花括号 “”对齐。u 通常情况下左花括号 “”单独成行，不与任何语句并列一行。u if、while、do语句后一定要使用，即使号中为空或只有一条语句。如 if (somevalue = 1) somevalue = 2; 2.5 程序注释2.5.1 注释一般原则u 修改代码时，总是使代码周围的注释保持最新。u 在每个例程的开始，提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍。u 所有的常量变量，无论是全局还是局部使用的，凡是对代码整体起到关键性做用的都需要加上注释。u 避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。 u 避免杂乱的注释，如一整行星号。而是应该使用空白将注释同代码分开。 u 避免在块注释的周围加上印刷框。这样看起来可能很漂亮，但是难于维护，但在文件头部总体注释中是允许的。u 在部署发布之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。u 如果需要用注释来解释复杂的代码节，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能，但必须保持性能和可维护性之间的平衡。u 在编写注释时使用完整的句子。注释应该阐明代码，而不应该增加多义性。 u 在编写代码时就注释，因为以后很可能没有时间这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。u 在需要的地方注释。可读性强的代码需要很少的注释，避免多余的或不适当的注释，如幽默的不主要的备注。u 使用注释来解释代码的意图。它们不应作为代码的联机翻译。 u 注释代码中不十分明显的任何内容。u 为了防止问题反复出现，对错误修复和解决方法代码总是使用注释，尤其是在团队环境中。u 当开发者维护以前的程序代码时，需要在修改处的开始及结尾，加上自己的注释信息。u 对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。 u 在整个应用程序中，使用具有一致的标点和结构的统一样式来构造注释。 u 用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释时，这样做会使注释很明显且容易被找到。u 在所有的代码修改处加上修改标识的注释。u 为了是层次清晰，在闭合的右花括号后注释该闭合所对应的起点。 namespace Langchao.Procument.Web / namespace Langchao.Procument.Webu 注释需和代码对齐u 如果必须要需大量的注释才能说明白某处的代码，那么此时应该检验此处程序代码是否该清晰、可读。u 对注释做拼写检查，保证语法和标点符号的正确使用。2.5.2 文档型注释 该类注释采用.Net已定义好的Xml标签来标记，在声明接口、类、方法、属性、字段都应该使用该类注释，以便代码完成后直接生成代码文档，让别人更好的了解代码的实现和接口。如/ / 下载文件/ / 源文件路径/ 源文件名称/ / 附注说明：public void DownLoad(string strPath,string strFileName)/这里是具体实现代码2.5.3 单行注释该类注释用于：方法内的代码注释。如变量的声明、代码或代码段的解释。注释示例：/ 注释语句private int number; 方法内变量的声明或花括号后的注释, 注释示例： if ( 1 = 1) / always true statement; / always true2.5.4 段落注释在一个方法中逻辑分段，以下几种注释方法均可：有编号注释/ 1.定义局部变量/2.数据有效性检验/2.1 参数有效性检验/ 2.2 数据库中数据有效性检验/3.处理过程/也可采用如下段落注释：/ 定义局部变量/ 数据有效性检验/数据处理过程/这两种段落注释都是正确的，但若第一种编注释编码一定要正确，代码改动时一定要保证编码有序。2.6 语句规范2.6.1 语句中使用相对路径并供用户可配置u 不在代码中使用具体的路径和驱动器名，使用相对路径，并使路径可编程2.6.2 每行语句避免超过一条u 每一行上放置的语句避免超过一条。如 nA +; /推荐 nB -; /推荐nA +; nB -; /不推荐u 当一行被分为几行时，通过将串联运算符放在每一行的末尾而不是开头，清楚地表示没有后面的行是不完整的。2.6.3 复合语句复合语句是指包含父语句子语句;子语句;的语句，使用复合语句应遵循以下几点：u 子语句要缩进。u 左花括号“” 在复合语句父语句的下一行并与之对齐，单独成行。u 即使只有一条子语句要不要省略花括号“ ”。 如 while (d += s+) n+; 2.6.4 return 语句u return语句中不使用括号，除非它能使