开发人员手册VSNET开发规范篇模板.doc

资源描述

密级：秘密开发人员手册 --VS.NET开发规范篇文档最终修订者及日期：孙立新 -3-16 本版文件同意人及日期：浪潮集团山东通用软件目录 1 导言 5 1.1 目标 5 1.2 适用范围 5 1.3 术语定义 5 1.4 参考资料 5 1.5 版本更新统计 5 2 使用开发工具： 6 3 程序源代码风格定义 6 3.1 代码结构风格 6 3.2 注释风格 7 3.2.1 单行注释 8 3.2.2 多行注释 8 3.2.3 文档型注释 8 3.2.4 文档型注释规范 11 3.3 代码书写风格 14 3.3.1 缩进 14 3.3.2 空行 14 3.3.3 换行 15 3.3.4 空格 15 3.3.5 花括号 16 4 命名规范 16 4.1 大写规则 16 4.2 区分大小写 17 4.3 缩写 18 4.4 措词 19 4.5 避免类型名称混淆 20 4.6 命名空间命名规范 22 4.7 类命名规范 23 4.8 接口命名规范 24 4.9 属性命名规范 25 4.10 枚举类型命名规范 25 4.11 静态字段命名规范 25 4.12 参数命名规范 26 4.13 方法命名规范 26 4.14 属性命名规范 26 4.15 事件命名规范 28 4.16 数据库对象命名规范 29 4.16.1 数据库名（开发过程中） 29 4.16.2 数据库表 29 4.16.3 字段 30 4.16.4 存放过程命名约定 31 4.16.5 触发器（插入，更新，删除）命名约定 31 4.16.6 视图命名约定 31 4.16.7 自定义数据类型命名约定 31 4.16.8 自定义函数命名约定 32 4.17 数据库表结构设计规范 33 4.18 数据库存放过程编写规范 34 5 界面规范 34 5.1 总则 34 5.2 遵从标准 34 5.3 色彩搭配 35 5.4 屏幕大小 35 5.5 主控页面 35 5.5.1 主页：登录窗口 35 5.5.2 主操作页分成三个区域：标题菜单区、系统管理区、操作区 36 5.5.3 浏览器 36 5.6 多种页面模板应用场景 37 5.6.1 字典类 37 5.6.2 单据类 38 5.6.3 管理类 39 5.6.4 索引类 40 5.6.5 Tab页类 40 5.6.6 响应式窗口类 40 5.6.7 查询结果/报表类 40 6 提醒信息规范 41 6.1 总则 41 6.2 提醒信息 41 7 热键定义、帮助及使用规范 41 7.1 总则 41 7.2 规范 41 8 单元测试规范（从开发人员角度） 42 8.1 总则 42 8.2 测试规范 42 9 配置管理规范（从开发人员角度） 43 9.1 总则 43 9.2 开发前准备 43 9.3 开发过程中规则 44 10 程序模板 44 10.1 总则 44 10.2 字典模板 45 10.3 单据模板 45 10.4 查询模板 45 11 其它规则及提议 46 1 导言 1.1 目标本文档是为基于Microsoft®企业Visual Studio .Net® - C#.Net系列开发工具进行软件开发一个规范性文件。其目标是： Ø 确保软件开发过程中有一个统一标准能够进行参考：包含类库、公共接口、设计模式、命名规范等。　 Ø 能够合理使用公用资源 1.2 适用范围本文档关键是基于现在三层架构开发模式中SmartClient方法进行描述，并一样适合于传统三层架构：A 1.3 术语定义可访问性修饰符：public（公有）、internal（内部公有）、proected（受保护）、protected internal（受保护或内部公有）、private（私有）。在此约定好中英文对照名称。非私有包含：公有、内部公有、受保护、受保护或内部公有。 1.4 参考资料 1. 《C# Language Specification1.2.doc》 2. 《C# Language Specification 2.0.doc》 1.5 版本更新统计版本/修订版修改确定日期修改内容概述起草人审核人备注 1.0 -10 初始版本鞠强曲丽君 2.0 -03 代码风格章节调整命名规范细化样式调整孙立新 2 使用开发工具： Ø Microsoft® Visual Studio .Net ® - C#.Net 3 程序源代码风格定义源代码风格规范是在编写源代码文件时，对于书写格式和规则统一要求。编写源代码最基础目标是能够经过编译生成可实施程序。另外，源代码另一个关键目标是为了阅读，源代码不仅仅是为了编译器能够读懂，同时也是为了人能够读懂，且易于读懂。这就如写文章句读、段落、章节等类似，假如没有一个良好书写风格和习惯，不仅仅会使写出文章难以阅读，而且可能会造成不少曲解。有句话叫“文如其人”，代码也一样是“文如其人”。另外，作为一个协作亲密开发团体，很有必需保持一致代码书写风格，它有利于团体开发保持高效（沟通交流、代码阅读、工作交接、工作延续性等方面）。 3.1 代码结构风格对于每一个代码文件（*.cs），它内容分为以下两个部分： u 使用命名空间 u 类型定义使用命名空间，要求必需全部申明在代码文件最前方。提议.net framework中定义命名空间放在最上面，然后依据和目前代码关系远近依次排列，对于引用命名空间，根据引用起源分段列示，段和段之间用空行分隔。示例图以下： using System; using System.Collections; using System.Collections.Generic; using DevExpress.XtraTreeList; using DevExpress.XtraTreeList.Nodes; using Genersoft.Platform.Core.Common; using Genersoft.Platform.Core.Error; 31 使用命名空间代码示例在类型定义部分，一个代码文件标准上只包含一个以下类型定义：类、接口、结构、枚举。这么有利于结构出条理清楚代码文件结构，一目了然。对于委托定义，可考虑在一个代码文件中集中定义内聚度较高一类枚举。对于类定义，根据一下次序定义： u 常量 u 字段 u 结构函数 u 析构函数 u 属性 u 方法 u 事件全部类组员必需显式申明访问修饰限定符（public、internal、protected、private）。为使类型含有良好封装性，其中字段类型只能申明为private。对于接口和结构体定义，其组员申明次序和类定义相同。每行代码只许可写一条语句。每行代码写多条语句往往会造成调试定位、注释和阅读困难。 3.2 注释风格传统注释风格：单行注释符号“//”和多行注释符号“/* */”在C#中仍然能够使用。在.NET中，提供了额外XML文档注释标识（Tags for Documentation Comments）。 3.2.1 单行注释单行注释，即形式为“//”注释。单行注释用于方法内代码注释。如对局部变量申明注释或代码行、代码段注释。单行注释可单独一行，假如仅仅针对一句注释，且不影响换行，可放于代码行后部。单行注释也能够用于临时屏蔽不用代码行，在开发完成后应立即清理。特殊，单行注释用于代码文件申明注释，见代码文件注释。 3.2.2 多行注释多行注释，即形式为“/* */”注释。通常，不提议在代码中使用多行注释。多行注释可用于临时屏蔽不用代码行，在开发完成后应立即清理。 3.2.3 文档型注释文档型注释，即XML文档注释标识（Tags for Documentation Comments），该类注释是.Net定义Xml标签，在申明接口、类、方法、属性、字段全部应该使用该类注释，除了在阅读代码时了解代码语义之外，可经过该类注释生成代码类库帮助文档（*.chm）。这些标识包含以下表全部内容：文档标签使用方法示意功效说明 <summary> <summary>description</summary> description：对象摘要。应该用于描述类型组员。使用 <remarks> 以提供相关类型本身信息。 <param> <param name="name">description</param> name：方法参数名。 description：参数说明。应该用于方法申明注释中，以描述方法一个参数。 <paramref> <paramref name="name"/> name：引用参数名。 <paramref> 标识为您提供了一个指示词为参数方法。能够处理 XML 文件，从而用某种独特方法格式化该参数。 <exception> <exception cref="member">description</exception> member：对可从目前编译环境中获取异常引用。编译器检验到给定异常存在后，将 member 转换为输出 XML 中规范化元素名。 description：异常使用条件说明。 <exception> 标识使您能够指定类能够引发异常。 <returns> <returns>description</returns> Description：返回值说明。 <returns> 标识应该用于方法申明注释，以描述返回值。 <see> <see cref="member"/> cref = "member"：对能够经过目前编译环境进行调用组员或字段引用。编译器检验到给定代码元素存在后，将 member 传输给输出 XML 中元素名。使您得以从文本内指定链接。使用 <seealso> 指示期望在“请参阅”一节中出现文本。 <seealso> <seealso cref="member"/> cref = "member"：对能够经过目前编译环境进行调用组员或字段引用。编译器检验到给定代码元素存在后，将 member 传输给输出 XML 中元素名。使您得以指定期望在“请参阅”一节中出现文本。使用 <see> 从文本 <example> <example>description</example> description：代码示例。使用 <example> 标识能够指定使用方法或其它库组员示例。通常情况下，这将包含到 <code> 标识使用。 <c> c>text</c> text：指示为代码文本。为您提供了一个将说明中文本标识为代码方法。使用 <code> 将多行指示为代码 <code> <code>content</code> content：标识为代码段文本。记为您提供了一个将多行指示为代码方法。使用 <c> 指示应将说明中文本标识为代码 <value> <value>property-description</value> property-description ：属性取值说明。 <value> 标识使您得以描述属性。请注意，当在 Visual Studio .NET 开发环境中经过代码向导添加属性时，它将会为新属性添加 <summary> 标识。然后，应该手动添加 <value> 标识以描述该属性所表示值。 <para> <para>content</para> Content：段落文本。用于诸如 <remarks> 或 <returns> 等标识内，使您得以将结构添加到文本中。 <include> <include file='filename' path='tagpath[@name="id"]' /> filename 包含文档文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。 Tagpath：filename 中指向标识名标识路径。将此路径括在单引号中 (' ')。 name 注释前边标识中名称说明符；名称含有一个 id。 id 在注释之前标识 id。将此 id 括在双引号中 (" ")。 <include> 标识使您得以引用描述源代码中类型和组员另一文件中注释。这是除了将文档注释直接置于源代码文件中之外另一个可选方法。 <include> 标识使用 XML XPath 语法。相关自定义 <include> 使用方法，请参阅 XPath 文档。 <list> <list type="bullet" | "number" | "table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item> </list> term ：定义项，该项将在 text 中定义。 description：目符号列表或编号列表中项或 term 定义。 <listheader> 块用于定义表或定义列表中标题行。定义表时，只需为标题中项提供一个项。列表中每一项用 <item> 块指定。创建定义列表时，既需要指定 term 也需要指定 text。不过，对于表、项目符号列表或编号列表，只需为 text 提供一个项。列表或表所拥有 <item> 块数能够依据需要而定。 <permission> <permission cref="member">description</permission> cref = "member" 对能够经过目前编译环境进行调用组员或字段引用。编译器检验到给定代码元素存在后，将 member 转换为输出 XML 中规范化元素名。必需将 member 括在双引号 (" ") 中。 description 组员访问说明。 <permission> 标识使您得以将组员访问记入文档。System.Security.PermissionSet 使您得以指定对组员访问。 <remarks> <remarks>description</remarks> description：备注说明。 <remarks> 标识是能够描述相关类或其它类型备注概述信息。 3.2.4 注释规范 3.2.4.1 代码文件注释对于每一个代码文件（*.cs），在文件起始位置添加注释，用以申明该代码文件用途、版本修订历史、作者、创建日期和版权申明等信息。 // =============================================================================== // 浪潮GS产品 // 功效用途定义。 // 请查看GS开发文档来了解相关这类型更多信息。 // =============================================================================== // 日期版本修改人描述 // =============================================================================== // 作者 // 日期 // 浪潮集团山东通用软件版权全部。保留全部权利。 // =============================================================================== 32 代码文件注释示例 3.2.4.2 类型定义注释在类型定义时，需要添加该类型功效用途说明注释。用途说明应为阅读者介绍该类型提供关键功效，并向使用者介绍该类使用时需要了解知识，不要泛泛而谈，内容空洞，应付了事。使用“<summary/>”标签，内部可依据需要添加合适标签，方便更清楚表示。 /// <summary> /// 安全管理服务调用接口工厂。用于为调用者创建<see cref="ISecurityServiceClient"/>。 /// <para>依据配置文件SecurityClientConfiguration小节定义配置信息，创建对应服务实现。</para> /// <para>若调用是<c>SecurityClientFactory.GetClient()</c>方法，是获取小节中UsingClient属性指定服务实现。</para> /// </summary> public static class SecurityClientFactory { … } 33 类型定义注释示例生成类库文档样式示例： 34 类型定义注释生成文档样式示例 3.2.4.3 组员申明注释在类内部，对于组员申明，注释应能够说明组员功效用途，假如组员带有参数和返回值，应说明对应含义。功效用途使用“<summary/>”标签。参数使用“<param/>”标签，返回值使用“<returns/>”标签，另可依据组员调用应注意问题和相关知识进行说明，可采取“<remarks/>” 标签进行备注说明，采取“<example/>” 标签提供编程Demo。示例以下： /// <summary> /// 获取指定配置安全管理服务调用接口。 /// </summary> /// <param name="configID">配置标识。对应于配置项中Code属性。</param> /// <returns>安全管理服务调用接口。</returns> /// <exception cref="SecurityException">假如是程序识别错误，将会抛出该类型异常。</exception> /// <remarks> /// 目前途序已经提供了三种服务调用实现，分别是：“当地调用（Local）”、“Web服务调用（WS）”、“Remoting调用（Remoting）”。 /// </remarks> /// <example><code> /// ISecurityServiceClient serviceClient = /// SecurityClientFactory.GetClient(SecurityClientFactory.WebService); /// </code></example> public static ISecurityServiceClient GetClient(string configID) { … } 35 类型定义注释代码示例生成类库文档样式示例： 36 类型定义注释生成文档样式示例 3.2.4.4 代码段注释在属性方法、组员方法内部代码实现，通常使用单行注释形式。示例以下： // 检验输入有效性 if (user == null) throw new SecurityException(SecurityError.NullUser); if (this.IsUserCodeInUsing(user.Id, user.Code) == true) // 若编号已经被其它用户使用 throw new SecurityException(SecurityError.UserCodeExist, ErrorLevel.Warning); // 获取事件代理，发出用户将被修改事件 ServiceManager.GetSecurityEventBroker().FireUserModifying(user); // 持久化存取接口 IUserRepository repository = this.GetRepository(); 37 代码段注释代码示例 3.3 代码书写风格以下是常常使用到部分代码格式要求： 3.3.1 缩进缩进是经过在每一行代码前端添加一定数量显示为空白符号，在显示上区分出代码行之间层次关系。一个缩进单位是4个空格符（不要直接使用Tab字符，VS.Net设置：工具->选项->文本编辑器->C#->制表符->插入空格）。同一语法层级多行语句要使用统一缩进单位。在命名空间、类型定义、属性方法定义、分支循环定义等表示嵌套包含关系时要使用一个缩进单位。假如一条语句超出一行，从第二行开始要使用一个缩进单位。 3.3.2 空行空行是在代码中添加只包含回车换行符空白行。空行能够依据代码行在语法、逻辑上相关性或内聚度分隔成多个代码块，从而提升代码可阅读性。在使用命名空间和类型定义之间要添加一个空行。假如在同一代码文件中申明了不一样类型，则在不一样类型定义之间要添加一个空行。在类型组员定义之间要添加一个空行（字段之间可没有），具体以下： 1. 方法、属性组员之间。 2. 属性和字段、方法和字段之间。 3. #region、#endregion和其它代码行之间。在一个方法内部（结构函数、属性方法、组员方法等）： 1. 方法中变量申明和语句之间。 2. 方法中多个逻辑步骤之间。 3. 方法中返回语句和其它语句之间。注释和它注释代码行之间不空行，但和其它代码行之间空一行。没有特殊原因，不许可出现连续空行。 3.3.3 换行假如一条语句过长（超出了80个字符，或超出代码编辑窗口显示宽度），会造成语句阅读上困难，必需对这条语句进行换行。换行要遵守缩进要求。换行位置选择，尽可能选择在操作符（“=”、“&&”、“||”、“,”等）以后，不破坏代码连贯性，易于了解。 SomeBlockEventBroker broker = ServiceManager.GetSomeBlockEventBroker() if (info.HitTest == GridHitTest.RowCell || info.HitTest == GridHitTest.RowIndicator) { this.DoSomething(); } return string.Format("SELECT 1 FROM {0} WHERE {1} = ‘{2}’", this.Table, this.PrimaryKey, obj.Id); 38 换行示例 3.3.4 空格空格即空格符。假如代码行中表示式字符之间没有空格，会显得代码很密集、局促，也不好阅读。添加适量空格，可有效缓解这种情况。在双目、三目运算符和操作数之间要添加空格。在左括号“(”和关键字之间要添加空格。在参数（形参和实参）多个参数之间要添加空格。在类型之间继承、实现关系“:”左右两侧要添加空格。在结构函数继承“:”左右两侧要添加空格。不要使用连续多个空格（缩进不在讨论范围内）。 3.3.5 花括号花括号单独占一行。左花括号“{”和上方相邻语句左对齐，保持同一缩进。右花括号“}” 和左花括号 “{”对齐，保持同一缩进。 4 命名规范一致命名模式是托管类库中可预知性和可发觉性最关键元素之一。对这些命名规范广泛使用和了解将消除很多最常见用户问题。本文提供 .NET Framework 类型命名规范。对于每个类型，还应该注意相关大写样式、区分大小写和措词部分通用规则。 4.1 大小写规则使用下面三种标识符约定： u Pascal 大小写规则将标识符首字母和后面连接每个单词首字母全部大写。能够对三字符或更多字符标识符使用 Pascal 大小写。比如：BackColor u Camel 大小写规则标识符首字母小写，而每个后面连接单词首字母全部大写。比如：backColor u 大写规则标识符中全部字母全部大写。仅对于由两个或更少字母组成标识符使用该约定。比如：System.IO、System.Web.UI 可能还必需大写标识符以维持和现有非托管符号方案兼容性，在该方案中全部大写字母常常见于枚举和常数值。通常情况下，在使用它们程序集之外这些字符应该是不可见。下表汇总了大写规则，并提供了不一样类型标识符示例。标识符大小写规则示例命名空间 Pascal System.Drawing 类 Pascal AppDomain 接口 Pascal IDisposable 注：总是以 I 前缀开始。枚举类型 Pascal ErrorLevel 枚举值 Pascal FatalError 委托 Pascal MouseDownEventHandler 私有常量 Camel fileType 非私有常量 Pascal FileType 只读静态字段 Pascal RedValue 私有静态字段 Camel serviceInstance 非私有静态字段 Pascal ConfigID 注：不提议使用，应使用静态属性。私有实例字段 Camel string code; 非私有实例字段 Pascal RedValue 注：不提议使用，应使用属性。属性 Pascal BackColor 方法 Pascal ToString 方法参数 Camel typeName 局部变量 Camel int index = 0; 事件 Pascal MouseDown 4.2 区分大小写为了避免混淆和确保跨语言交互操作，请遵照相关区分大小写使用下列规则： 1. 不要使用要求区分大小写名称。对于区分大小写和不区分大小写语言，组件全部必需完全能够使用。不区分大小写语言无法区分同一上下文中仅大小写不一样两个名称。所以，在创建组件或类中必需避免这种情况。 2. 不要创建仅是名称大小写有区分两个命名空间。比如不区分大小写语言无法区分以下两个命名空间申明： namespace ee.cummings; namespace Ee.Cummings; 3. 不要创建含有仅是大小写有区分参数名称函数。下面示例是不正确。 void MyFunction(string a, string A) 4. 不要创建含有仅是大小写有区分类型名称命名空间。在下面示例中，Point p 和 POINT p 是不合适类型名称，原因是它们仅在大小写方面有区分。比如：System.Windows.Forms.Point p System.Windows.Forms.POINT p 5. 不要创建含有仅是大小写有区分属性名称类型。在下面示例中，int Color 和 int COLOR 是不合适属性名称，原因是它们仅在大小写方面有区分。比如：int Color {get, set} int COLOR {get, set} 6. 不要创建含有仅是大小写有区分方法名称类型。在下面示例中，calculate 和 Calculate 是不合适方法名称，原因是它们仅在大小写方面有区分。比如：void calculate() void Calculate() 4.3 缩写为了避免混淆和确保跨语言交互操作，区分缩写使用下列规则： 1. 不要将缩写或缩略形式用作标识符名称组成部分。比如，使用 GetWindow，而不要使用 GetWin。 2. 不要使用计算机领域中未被普遍接收缩写。 3. 在合适时候，使用众所周知缩写替换冗长词组名称。比如，用 UI 作为 User Interface 缩写；用 OLAP 作为 On-line Analytical Processing 缩写。 4. 在使用缩写时，对于超出两个字符长度缩写，使用 Pascal 大小写或 Camel 大小写。比如，使用 HtmlButton 或 htmlButton。不过，应该大写仅有两个字符缩写，如，System.IO，而不是 System.Io。 5. 不要在标识符或参数名称中使用缩写。假如必需使用缩写，对于由多于两个字符所组成缩写请使用 Camel 大小写，即使这和单词标准缩写相冲突。 4.4 措词避免使用和常见 .NET Framework 命名空间反复类名称。比如，不要将以下任何名称用作类名称：System、Collections、Forms 或 UI。相关 .NET Framework 命名空间列表，请参见类库。另外，避免使用和以下关键字冲突标识符： CStr CType Date Decimal Declare Default Delegate Dim Do Double Each Else ElseIf End Enum Erase Error Event Exit ExternalSource FALSE Finalize Finally Float For Friend Function Get GetType Goto Handles If Implements Imports In Inherits Integer Interface Is Let Lib Like Long Loop Me Mod Module MustInherit MustOverride MyBase MyClass Namespace New Next Not Nothing NotInheritable NotOverridable Object On Option Optional Or Overloads Overridable Overrides ParamArray Preserve Private Property Protected Public RaiseEvent ReadOnly ReDim Region REM RemoveHandler Resume Return Select Set Shadows Shared Short Single Static Step Stop String Structure Sub SyncLock Then Throw To TRUE Try TypeOf Unicode Until volatile When While With WithEvents WriteOnly Xor eval extends instanceof package var 4.5 避免类型名称混淆不一样编程语言使用不一样术语标识基础托管类型。类库设计人员必需避免使用语言特定术语。请遵照本节中描述规则以避免类型名称混淆。使用描述类型含义名称，而不是描述类型名称。假如参数除了其类型之外没有任何语义含义，那么在这种罕见情况下请使用通常性名称。比如，支持将多种数据类型写入到流中类能够有以下方法。 [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 intValue); void Write(short shortValue); 下表列出基础数据类型名称和它们通用替换。 C# 类型名称 Visual Basic 类型名称 JScript 类型名称 Visual C++ 类型名称 <Ilasm.exe> 表示形式通用类型名称 sbyte SByte sByte char int8 SByte byte Byte byte unsigned char unsigned int8 Byte short Short short short int16 Int16 ushort UInt16 ushort unsigned short unsigned int16 UInt16 int Integer int int int32 Int32 uint UInt32 uint unsigned int unsigned int32 UInt32 long Long long __int64 int64 Int64 ulong UInt64 ulong unsigned __int64 unsigned int64 UInt64 float Single float float float32 Single double Double double double float64 Double bool Boolean boolean bool bool Boolean char Char char wchar_t char Char string String string String string String object Object object Object object Object 比如，支持将从流读取多种数据类型类能够有以下方法。 [C#] double ReadDouble(); float ReadSingle(); long ReadInt64(); int ReadInt32(); short ReadInt16(); 上面示例优先于下面语言特定替换方法。 [C#] double ReadDouble(); float ReadFloat(); long ReadLong(); int ReadInt(); short ReadShort(); 4.6 命名空间命名规范命名命名空间时通常性规则是使用企业名称，后跟技术名称和可选功效和设计，以下所表示。 CompanyName.TechnologyName[

展开阅读全文