《开发人员手册(VSNET开发规范篇).docx》由会员分享，可在线阅读，更多相关《开发人员手册(VSNET开发规范篇).docx（49页珍藏版）》请在三一办公上搜索。
1、密级：秘密 开 发 人 员 手 册 -VS.NET开发规范篇文档最后修订者及日期：孙立新2009-3-16本版文件批准人及日期：浪潮集团山东通用软件有限公司目录1导言51.1目的51.2适用范围51.3术语定义51.4参考资料51.5版本更新记录52使用的开发工具：63程序源代码风格定义63.1代码结构风格63.2注释风格73.2.1单行注释83.2.2多行注释83.2.3文档型注释83.2.4文档型注释规范113.3代码书写风格143.3.1缩进143.3.2空行143.3.3换行153.3.4空格153.3.5花括号164命名规范164.1大写规则164.2区分大小写174.3缩写184.
2、4措词194.5避免类型名称混淆204.6命名空间命名规范224.7类命名规范234.8接口命名规范244.9属性命名规范254.10枚举类型命名规范254.11静态字段命名规范254.12参数命名规范264.13方法命名规范264.14属性命名规范264.15事件命名规范284.16数据库对象命名规范294.16.1数据库名（开发过程中）294.16.2数据库表294.16.3字段304.16.4存储过程命名约定314.16.5触发器（插入，更新，删除）命名约定314.16.6视图命名约定314.16.7自定义数据类型命名约定314.16.8自定义函数命名约定324.17数据库表结构设计规范
3、334.18数据库存储过程编写规范345界面规范345.1总则345.2遵从原则345.3色彩搭配355.4屏幕大小355.5主控页面355.5.1主页：登录窗口355.5.2主操作页分成三个区域：标题菜单区、系统管理区、操作区365.5.3浏览器365.6各种页面模板应用的场景375.6.1字典类375.6.2单据类385.6.3管理类395.6.4索引类405.6.5Tab页类405.6.6响应式窗口类405.6.7查询结果/报表类406提示信息规范416.1总则416.2提示信息417热键定义、帮助及使用规范417.1总则417.2规范418单元测试规范（从开发人员角度）428.1总则4
4、28.2测试规范429配置管理规范（从开发人员角度）439.1总则439.2开发前的准备439.3开发过程中的规则4410程序模板4410.1总则4410.2字典模板4510.3单据模板4510.4查询模板4511其他规则及建议461 导言1.1 目的本文档是为基于Microsoft公司的Visual Studio .Net - C#.Net系列开发工具进行软件开发的一个规范性文件。其目的是： 保证软件开发过程中有一个统一的标准可以进行参照：包括类库、公共接口、设计模式、命名规范等。 能够合理的使用公用资源1.2 适用范围本文档主要是基于目前三层架构开发模式中的SmartClient方式进行描
5、述的，并同样适合于传统的三层架构：A1.3 术语定义可访问性修饰符：public（公有）、internal（内部公有）、proected（受保护）、protected internal（受保护或内部公有）、private（私有）。在此约定好中英文对照名称。非私有包括：公有、内部公有、受保护、受保护或内部公有。1.4 参考资料1. C# Language Specification1.2.doc2. C# Language Specification 2.0.doc1.5 版本更新记录版本/修订版修改确认日期修改内容概述起草人审核人备注1.02003-10初始版本鞠强曲丽君2.02008-03代
6、码风格章节调整命名规范细化样式调整孙立新2 使用的开发工具： Microsoft Visual Studio .Net 2005 - C#.Net3 程序源代码风格定义源代码风格规范是在编写源代码文件时，对于书写格式和规则的统一要求。编写源代码最基本的目标是能够经过编译生成可执行程序。此外，源代码的另一个主要目标是为了阅读，源代码不仅仅是为了编译器能够读懂，同时也是为了人能够读懂，且易于读懂。这就如写文章的句读、段落、章节等类似，如果没有一种良好的书写风格和习惯，不仅仅会使写出的文章难以阅读，而且可能会造成不少曲解。有句话叫“文如其人”，代码也同样是“文如其人”。此外，作为一个协作密切的开发团
7、队，非常有必要保持一致的代码书写风格，它有助于团队开发保持高效（沟通交流、代码阅读、工作交接、工作延续性等方面）。3.1 代码结构风格对于每一个代码文件（*.cs），它的内容分为如下两个部分：u 使用的命名空间u 类型定义使用的命名空间，要求必须都声明在代码文件的最前方。建议.net framework中定义的命名空间放在最上面，然后根据与当前代码关系的远近依次排列，对于引用的命名空间，按照引用来源分段列示，段与段之间用空行分隔。示例图如下：using System;using System.Collections;using System.Collections.Generic;using
8、DevExpress.XtraTreeList;using DevExpress.XtraTreeList.Nodes;using Genersoft.Platform.Core.Common;using Genersoft.Platform.Core.Error;31 使用的命名空间代码示例在类型定义部分，一个代码文件原则上只包含一个如下类型的定义：类、接口、结构、枚举。这样有利于构造出条理清晰的代码文件结构，一目了然。对于委托的定义，可考虑在一个代码文件中集中定义内聚度较高的一类枚举。对于类的定义，按照一下顺序定义：u 常量u 字段u 构造函数u 析构函数u 属性u 方法u 事件所有的类成
9、员必须显式的声明访问修饰限定符（public、internal、protected、private）。为使类型具有良好的封装性，其中字段类型只能声明为private。对于接口和结构体定义，其成员声明顺序与类定义相同。每行代码只允许写一条语句。每行代码写多条语句往往会造成调试定位、注释以及阅读的困难。3.2 注释风格传统的注释风格：单行注释符号“/”和多行注释符号“/* */”在C#中依然可以使用。在.NET中，提供了额外的XML文档注释标记（Tags for Documentation Comments）。3.2.1 单行注释单行注释，即形式为“/”的注释。单行注释用于方法内的代码注释。如对局
10、部变量声明的注释或代码行、代码段的注释。单行注释可单独一行，如果仅仅针对一句注释，且不影响换行，可放于代码行后部。单行注释也可以用于临时屏蔽不用的代码行，在开发完毕后应及时清理。特殊的，单行注释用于代码文件声明的注释，见代码文件注释。3.2.2 多行注释多行注释，即形式为“/* */”的注释。一般的，不建议在代码中使用多行注释。多行注释可用于临时屏蔽不用的代码行，在开发完毕后应及时清理。3.2.3 文档型注释文档型注释，即XML文档注释标记（Tags for Documentation Comments），该类注释是.Net定义的Xml标签，在声明接口、类、方法、属性、字段都应该使用该类注释，
11、除了在阅读代码时了解代码语义之外，可通过该类注释生成代码类库的帮助文档（*.chm）。这些标记包括如下表的全部内容：文档标签用法示意功能说明descriptiondescription：对象的摘要。应当用于描述类型成员。使用 以提供有关类型本身的信息。descriptionname：方法参数名。description：参数的说明。应当用于方法声明的注释中，以描述方法的一个参数。 name：引用的参数名。 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件，从而用某种独特的方法格式化该参数。descriptionmember：对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存
12、在后，将 member 转换为输出 XML 中的规范化元素名。description：异常使用条件说明。 标记使您可以指定类能够引发的异常。 descriptionDescription：返回值的说明。 标记应当用于方法声明的注释，以描述返回值。cref = member：对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。使您得以从文本内指定链接。使用 指示希望在“请参阅”一节中出现的文本。cref = member：对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 membe
13、r 传递给输出 XML 中的元素名。使您得以指定希望在“请参阅”一节中出现的文本。使用 从文本descriptiondescription：代码示例。使用 标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到 标记的使用。ctext text：指示为代码的文本。为您提供了一种将说明中的文本标记为代码的方法。使用 将多行指示为代码contentcontent：标记为代码段的文本。 记为您提供了一种将多行指示为代码的方法。使用 指示应将说明中的文本标记为代码 property-descriptionproperty-description ：属性取值的说明。 标记使您得以描述属性。请注意
14、，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 标记。然后，应该手动添加 标记以描述该属性所表示的值。contentContent：段落文本。用于诸如 或 等标记内，使您得以将结构添加到文本中。filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 ( )。 Tagpath：filename 中指向标记名的标记路径。将此路径括在单引号中 ( )。 name 注释前边的标记中的名称说明符；名称具有一个 id。 id 位于注释之前的标记的 id。将此 id 括在双引号中 ( )。 标记使您得以引用描述源代
15、码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。 标记使用 XML XPath 语法。有关自定义 使用的方法，请参阅 XPath 文档。 term description term description term ：定义的项，该项将在 text 中定义。 description：目符号列表或编号列表中的项或者 term 的定义。 块用于定义表或定义列表中的标题行。定义表时，只需为标题中的项提供一个项。列表中的每一项用 块指定。创建定义列表时，既需要指定 term 也需要指定 text。但是，对于表、项目符号列表或编号列表，只需为 text 提供一
16、个项。列表或表所拥有的 块数可以根据需要而定。descriptioncref = member 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 ( ) 中。 description 成员的访问的说明。 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。descriptiondescription：备注说明。 标记是可以描述有关类或其他类型的备注概述信息。3.2.4 注释规范3.2.4.1 代码文件注释对
17、于每一个代码文件（*.cs），在文件起始位置添加注释，用以声明该代码文件的用途、版本修订历史、作者、创建日期以及版权声明等信息。/ =/ 浪潮GS产品/ 功能用途定义。/ 请查看GS开发文档来了解关于此类型的更多信息。/ =/ 日期 版本修改人 描述/ =/ 作者/ 日期/ 浪潮集团山东通用软件有限公司版权所有。保留所有权利。/ =32 代码文件注释示例3.2.4.2 类型定义注释在类型定义时，需要添加该类型的功能用途说明的注释。用途说明应为阅读者介绍该类型提供的主要功能，并向使用者介绍该类使用时需要了解的知识，不要泛泛而谈，内容空洞，应付了事。使用“”标签，内部可根据需要添加适当的标签，以便
18、更清楚的表达。/ / 安全管理服务调用接口工厂。用于为调用者创建。/ 根据配置文件的SecurityClientConfiguration小节定义的配置信息，创建相应的服务实现。/ 若调用的是SecurityClientFactory.GetClient()方法，是获取小节中的UsingClient属性指定的服务实现。/ public static class SecurityClientFactory 33 类型定义注释示例生成的类库文档样式示例：34 类型定义注释生成文档样式示例3.2.4.3 成员声明注释在类的内部，对于成员的声明，注释应能够说明成员的功能用途，如果成员带有参数和返回值，
19、应说明相应的含义。功能用途使用“”标签。参数使用“”标签，返回值使用“”标签，另可根据成员的的调用应注意的问题和相关知识进行说明，可采用“” 标签进行备注说明，采用“” 标签提供编程Demo。示例如下：/ / 获取指定配置的安全管理服务调用接口。/ / 配置标识。对应于配置项中的Code属性。/ 安全管理服务调用接口。/ 如果是程序识别的错误，将会抛出该类型的异常。/ / 当前程序已经提供了三种服务调用实现，分别是：“本地调用（Local）”、“Web服务调用（WS）”、“Remoting调用（Remoting）”。/ / / ISecurityServiceClient serviceCli
20、ent = / SecurityClientFactory.GetClient(SecurityClientFactory.WebService);/ public static ISecurityServiceClient GetClient(string configID) 35 类型定义注释代码示例生成的类库文档样式示例：36 类型定义注释生成文档样式示例3.2.4.4 代码段注释位于属性方法、成员方法内部代码实现，一般使用单行注释形式。示例如下：/ 检查输入有效性if (user = null) throw new SecurityException(SecurityError.Nul
21、lUser);if (this.IsUserCodeInUsing(user.Id, user.Code) = true) / 若编号已经被其他用户使用 throw new SecurityException(SecurityError.UserCodeExist, ErrorLevel.Warning);/ 获取事件代理，发出用户将被修改的事件ServiceManager.GetSecurityEventBroker().FireUserModifying(user);/ 持久化存取接口IUserRepository repository = this.GetRepository();37
22、代码段注释代码示例3.3 代码书写风格以下是经常使用到的一些代码格式要求：3.3.1 缩进缩进是通过在每一行代码的前端添加一定数量的显示为空白的符号，在显示上区分出代码行之间的层次关系。一个缩进单位是4个空格符（不要直接使用Tab字符，VS.Net设置：工具-选项-文本编辑器-C#-制表符-插入空格）。同一语法层级的多行语句要使用统一的缩进单位。在命名空间、类型定义、属性方法定义、分支循环定义等表达嵌套包含关系时要使用一个缩进单位。如果一条语句超过一行，从第二行开始要使用一个缩进单位。3.3.2 空行空行是在代码中添加的只包含回车换行符的空白行。空行可以根据代码行在语法、逻辑上的相关性或内聚度
23、分隔成多个代码块，从而提高代码的可阅读性。在使用命名空间与类型定义之间要添加一个空行。如果在同一代码文件中声明了不同的类型，则在不同的类型定义之间要添加一个空行。在类型的成员定义之间要添加一个空行（字段之间可没有），具体如下：1. 方法、属性成员之间。2. 属性与字段、方法与字段之间。3. #region、#endregion与其他代码行之间。在一个方法内部（构造函数、属性方法、成员方法等）：1. 方法中变量声明与语句之间。2. 方法中的多个逻辑步骤之间。3. 方法中的返回语句与其他的语句之间。注释与它注释的代码行之间不空行，但与其他的代码行之间空一行。没有特殊原因，不允许出现连续空行。3.3
24、.3 换行如果一条语句过长（超过了80个字符，或者超过代码编辑窗口的显示宽度），会造成语句阅读上的困难，必须对这条语句进行换行。换行要遵守缩进的要求。换行的位置的选择，尽量选择在操作符（“=”、“&”、“|”、“,”等）之后，不破坏代码的连贯性，易于理解。SomeBlockEventBroker broker = ServiceManager.GetSomeBlockEventBroker()if (info.HitTest = GridHitTest.RowCell | info.HitTest = GridHitTest.RowIndicator) this.DoSomething();r
25、eturn string.Format(SELECT 1 FROM 0 WHERE 1 = 2, this.Table, this.PrimaryKey, obj.Id);38 换行示例3.3.4 空格空格即空格符。如果代码行中的表达式字符之间没有空格，会显得代码很密集、局促，也不好阅读。添加适量的空格，可有效缓解这种情况。在双目、三目运算符和操作数之间要添加空格。在左括号“(”与关键字之间要添加空格。在参数（形参和实参）的多个参数之间要添加空格。在类型之间的继承、实现关系的“:”左右两侧要添加空格。在构造函数的继承的“:”左右两侧要添加空格。不要使用连续多个空格（缩进不在讨论范围内）。3.3
26、.5 花括号花括号单独占一行。左花括号“”与上方相邻语句左对齐，保持同一缩进。右花括号“” 与左花括号 “”对齐，保持同一缩进。4 命名规范一致的命名模式是托管类库中可预知性与可发现性最重要的元素之一。对这些命名规范广泛的使用和理解将消除许多最常见的用户问题。本文提供 .NET Framework 类型的命名规范。对于每个类型，还应该注意关于大写样式、区分大小写和措词的一些通用规则。4.1 大小写规则 使用下面的三种标识符约定：u Pascal 大小写规则将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。例如：BackColoru C
27、amel 大小写规则标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：backColoru 大写规则标识符中的所有字母都大写。仅对于由两个或者更少字母组成的标识符使用该约定。例如：System.IO、System.Web.UI可能还必须大写标识符以维持与现有非托管符号方案的兼容性，在该方案中所有大写字母经常用于枚举和常数值。一般情况下，在使用它们的程序集之外这些字符应当是不可见的。下表汇总了大写规则，并提供了不同类型的标识符的示例。标识符大小写规则示例命名空间PascalSystem.Drawing类PascalAppDomain接口PascalIDisposable 注：总是以
28、I 前缀开始。枚举类型PascalErrorLevel枚举值PascalFatalError委托PascalMouseDownEventHandler私有的常量CamelfileType非私有的常量PascalFileType只读的静态字段PascalRedValue私有的静态字段CamelserviceInstance非私有的静态字段PascalConfigID注：不建议使用，应使用静态属性。私有实例字段Camelstring code;非私有的实例字段PascalRedValue 注：不建议使用，应使用属性。属性PascalBackColor方法PascalToString方法参数Came
29、ltypeName局部变量Camelint index = 0;事件PascalMouseDown4.2 区分大小写 为了避免混淆和保证跨语言交互操作，请遵循有关区分大小写的使用的下列规则： 1. 不要使用要求区分大小写的名称。对于区分大小写和不区分大小写的语言，组件都必须完全可以使用。不区分大小写的语言无法区分同一上下文中仅大小写不同的两个名称。因此，在创建的组件或类中必须避免这种情况。 2. 不要创建仅是名称大小写有区别的两个命名空间。例如不区分大小写的语言无法区分以下两个命名空间声明：namespace ee.cummings;namespace Ee.Cummings;3. 不要创建具
30、有仅是大小写有区别的参数名称的函数。下面的示例是不正确的。 void MyFunction(string a, string A)4. 不要创建具有仅是大小写有区别的类型名称的命名空间。在下面的示例中，Point p 和 POINT p 是不适当的类型名称，原因是它们仅在大小写方面有区别。 例如：System.Windows.Forms.Point pSystem.Windows.Forms.POINT p5. 不要创建具有仅是大小写有区别的属性名称的类型。在下面的示例中，int Color 和 int COLOR 是不适当的属性名称，原因是它们仅在大小写方面有区别。 例如：int Color
31、 get, setint COLOR get, set6. 不要创建具有仅是大小写有区别的方法名称的类型。在下面的示例中，calculate 和 Calculate 是不适当的方法名称，原因是它们仅在大小写方面有区别。 例如：void calculate()void Calculate()4.3 缩写 为了避免混淆和保证跨语言交互操作，区分缩写使用下列规则： 1. 不要将缩写或缩略形式用作标识符名称的组成部分。例如，使用 GetWindow，而不要使用 GetWin。 2. 不要使用计算机领域中未被普遍接受的缩写。 3. 在适当的时候，使用众所周知的缩写替换冗长的词组名称。例如，用 UI 作为
32、 User Interface 的缩写；用 OLAP 作为 On-line Analytical Processing 的缩写。 4. 在使用缩写时，对于超过两个字符长度的缩写，使用 Pascal 大小写或 Camel 大小写。例如，使用 HtmlButton 或 htmlButton。但是，应当大写仅有两个字符的缩写，如，System.IO，而不是 System.Io。 5. 不要在标识符或参数名称中使用缩写。如果必须使用缩写，对于由多于两个字符所组成的缩写请使用 Camel 大小写，虽然这和单词的标准缩写相冲突。4.4 措词 避免使用与常用的 .NET Framework 命名空间重复的类
33、名称。例如，不要将以下任何名称用作类名称：System、Collections、Forms 或 UI。有关 .NET Framework 命名空间的列表，请参见类库。另外，避免使用与以下关键字冲突的标识符：CStrCTypeDateDecimalDeclareDefaultDelegateDimDoDoubleEachElseElseIfEndEnumEraseErrorEventExitExternalSourceFALSEFinalizeFinally FloatForFriendFunctionGetGetTypeGotoHandlesIfImplementsImportsInInher
34、itsIntegerInterfaceIsLetLibLikeLongLoop MeModModuleMustInheritMustOverrideMyBaseMyClassNamespaceNewNextNotNothingNotInheritableNotOverridableObjectOnOptionOptionalOrOverloadsOverridableOverridesParamArrayPreservePrivatePropertyProtectedPublicRaiseEventReadOnlyReDimRegionREMRemoveHandlerResumeReturnS
35、electSetShadowsSharedShortSingleStaticStepStopStringStructureSubSyncLockThenThrowToTRUETryTypeOfUnicodeUntilvolatileWhenWhileWithWithEventsWriteOnlyXorevalextendsinstanceofpackagevar4.5 避免类型名称混淆不同的编程语言使用不同的术语标识基本托管类型。类库设计人员必须避免使用语言特定的术语。请遵循本节中描述的规则以避免类型名称混淆。使用描述类型的含义的名称，而不是描述类型的名称。如果参数除了其类型之外没有任何语义含
36、义，那么在这种罕见的情况下请使用一般性名称。例如，支持将各种数据类型写入到流中的类可以有以下方法。 C#void Write(double value);void Write(float value);void Write(long value);void Write(int value);void Write(short value);不要创建语言特定的方法名称，如下面的示例所示。 C#void Write(double doubleValue);void Write(float floatValue);void Write(long longValue);void Write(int in
37、tValue);void Write(short shortValue);下表列出基本数据类型名称和它们的通用替换。C# 类型名称Visual Basic 类型名称JScript 类型名称Visual C+ 类型名称 表示形式通用类型名称sbyteSBytesBytecharint8SBytebyteBytebyteunsigned charunsigned int8ByteshortShortshortshortint16Int16ushortUInt16ushortunsigned shortunsigned int16UInt16intIntegerintintint32Int32uin
38、tUInt32uintunsigned intunsigned int32UInt32longLonglong_int64int64Int64ulongUInt64ulongunsigned _int64unsigned int64UInt64floatSinglefloatfloatfloat32SingledoubleDoubledoubledoublefloat64DoubleboolBooleanbooleanboolboolBooleancharCharcharwchar_tcharCharstringStringstringStringstringStringobjectObjectobjectObjectobjectObject例如，支持将从流读取各种数据类型的类可以有以下方法。C#double ReadDouble();float ReadSingle();
