开发人员手册VSNET开发规范篇.docx
《开发人员手册VSNET开发规范篇.docx》由会员分享，可在线阅读，更多相关《开发人员手册VSNET开发规范篇.docx（46页珍藏版）》请在冰豆网上搜索。
开发人员手册VSNET开发规范篇
密级：
秘密
开发人员手册
--VS.NET开发规范篇
文档最后修订者及日期：
孙立新
2009-3-16
本版文件批准人及日期：
浪潮集团山东通用软件有限公司
1
导言
1.1目的
本文档是为基于Microsoft®公司的VisualStudio.Net®-C#.Net系列开发工具进行软件开发的一个规范性文件。
其目的是：
Ø保证软件开发过程中有一个统一的标准可以进行参照：
包括类库、公共接口、设计模式、命名规范等。
Ø能够合理的使用公用资源
1.2适用范围
本文档主要是基于目前三层架构开发模式中的SmartClient方式进行描述的，并同样适合于传统的三层架构：
A
1.3术语定义
可访问性修饰符：
public（公有）、internal（内部公有）、proected（受保护）、protectedinternal（受保护或内部公有）、private（私有）。
在此约定好中英文对照名称。
非私有包括：
公有、内部公有、受保护、受保护或内部公有。
1.4参考资料
1.《C#LanguageSpecification1.2.doc》
2.《C#LanguageSpecification2.0.doc》
1.5版本更新记录
版本/修订版
修改确认日期
修改内容概述
起草人
审核人
备注
1.0
2003-10
初始版本
鞠强
曲丽君
2.0
2008-03
代码风格章节调整
命名规范细化
样式调整
孙立新
2使用的开发工具：
ØMicrosoft®VisualStudio.Net2005®-C#.Net
3程序源代码风格定义
源代码风格规范是在编写源代码文件时，对于书写格式和规则的统一要求。
编写源代码最基本的目标是能够经过编译生成可执行程序。
此外，源代码的另一个主要目标是为了阅读，源代码不仅仅是为了编译器能够读懂，同时也是为了人能够读懂，且易于读懂。
这就如写文章的句读、段落、章节等类似，如果没有一种良好的书写风格和习惯，不仅仅会使写出的文章难以阅读，而且可能会造成不少曲解。
有句话叫“文如其人”，代码也同样是“文如其人”。
此外，作为一个协作密切的开发团队，非常有必要保持一致的代码书写风格，它有助于团队开发保持高效（沟通交流、代码阅读、工作交接、工作延续性等方面）。
3.1代码结构风格
对于每一个代码文件（*.cs），它的内容分为如下两个部分：
◆使用的命名空间
◆类型定义
使用的命名空间，要求必须都声明在代码文件的最前方。
建议.netframework中定义的命名空间放在最上面，然后根据与当前代码关系的远近依次排列，对于引用的命名空间，按照引用来源分段列示，段与段之间用空行分隔。
示例图如下：
在类型定义部分，一个代码文件原则上只包含一个如下类型的定义：
类、接口、结构、枚举。
这样有利于构造出条理清晰的代码文件结构，一目了然。
对于委托的定义，可考虑在一个代码文件中集中定义内聚度较高的一类枚举。
对于类的定义，按照一下顺序定义：
◆常量
◆字段
◆构造函数
◆析构函数
◆属性
◆方法
◆事件
所有的类成员必须显式的声明访问修饰限定符（public、internal、protected、private）。
为使类型具有良好的封装性，其中字段类型只能声明为private。
对于接口和结构体定义，其成员声明顺序与类定义相同。
每行代码只允许写一条语句。
每行代码写多条语句往往会造成调试定位、注释以及阅读的困难。
3.2注释风格
传统的注释风格：
单行注释符号“//”和多行注释符号“/**/”在C#中依然可以使用。
在.NET中，提供了额外的XML文档注释标记（TagsforDocumentationComments）。
3.2.1单行注释
单行注释，即形式为“//”的注释。
单行注释用于方法内的代码注释。
如对局部变量声明的注释或代码行、代码段的注释。
单行注释可单独一行，如果仅仅针对一句注释，且不影响换行，可放于代码行后部。
单行注释也可以用于临时屏蔽不用的代码行，在开发完毕后应及时清理。
特殊的，单行注释用于代码文件声明的注释，见代码文件注释。
3.2.2多行注释
多行注释，即形式为“/**/”的注释。
一般的，不建议在代码中使用多行注释。
多行注释可用于临时屏蔽不用的代码行，在开发完毕后应及时清理。
3.2.3文档型注释
文档型注释，即XML文档注释标记（TagsforDocumentationComments），该类注释是.Net定义的Xml标签，在声明接口、类、方法、属性、字段都应该使用该类注释，除了在阅读代码时了解代码语义之外，可通过该类注释生成代码类库的帮助文档（*.chm）。
这些标记包括如下表的全部内容：
文档标签
用法示意
功能说明
description
description：
对象的摘要。
应当用于描述类型成员。
使用以提供有关类型本身的信息。
description
name：
方法参数名。
description：
参数的说明。
应当用于方法声明的注释中，以描述方法的一个参数。
name：
引用的参数名。
标记为您提供了一种指示词为参数的方法。
可以处理XML文件，从而用某种独特的方法格式化该参数。
description
member：
对可从当前编译环境中获取的异常的引用。
编译器检查到给定异常存在后，将member转换为输出XML中的规范化元素名。
description：
异常使用条件说明。
标记使您可以指定类能够引发的异常。
description
Description：
返回值的说明。
标记应当用于方法声明的注释，以描述返回值。
cref="member"：
对可以通过当前编译环境进行调用的成员或字段的引用。
编译器检查到给定代码元素存在后，将member传递给输出XML中的元素名。
使您得以从文本内指定链接。
使用指示希望在“请参阅”一节中出现的文本。
cref="member"：
对可以通过当前编译环境进行调用的成员或字段的引用。
编译器检查到给定代码元素存在后，将member传递给输出XML中的元素名。
使您得以指定希望在“请参阅”一节中出现的文本。
使用从文本
description
description：
代码示例。
使用标记可以指定使用方法或其他库成员的示例。
一般情况下，这将涉及到标记的使用。
c>text
text：
指示为代码的文本。
为您提供了一种将说明中的文本标记为代码的方法。
使用将多行指示为代码
content
content：
标记为代码段的文本。
记为您提供了一种将多行指示为代码的方法。
使用指示应将说明中的文本标记为代码
property-description
property-description：
属性取值的说明。
标记使您得以描述属性。
请注意，当在VisualStudio.NET开发环境中通过代码向导添加属性时，它将会为新属性添加标记。
然后，应该手动添加标记以描述该属性所表示的值。
content
Content：
段落文本。
用于诸如或等标记内，使您得以将结构添加到文本中。
filename包含文档的文件名。
该文件名可用路径加以限定。
将filename括在单引号中（''）。
Tagpath：
filename中指向标记名的标记路径。
将此路径括在单引号中（''）。
name注释前边的标记中的名称说明符；名称具有一个id。
id
位于注释之前的标记的id。
将此id括在双引号中（""）。
标记使您得以引用描述源代码中类型和成员的另一文件中的注释。
这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。
标记使用XMLXPath语法。
有关自定义使用的方法，请参阅XPath文档。
term
description
term
description
term：
定义的项，该项将在text中定义。
description：
目符号列表或编号列表中的项或者term的定义。
块用于定义表或定义列表中的标题行。
定义表时，只需为标题中的项提供一个项。
列表中的每一项用- 块指定。
创建定义列表时，既需要指定term也需要指定text。
但是，对于表、项目符号列表或编号列表，只需为text提供一个项。
列表或表所拥有的- 块数可以根据需要而定。
description
cref="member"对可以通过当前编译环境进行调用的成员或字段的引用。
编译器检查到给定代码元素存在后，将member转换为输出XML中的规范化元素名。
必须将member括在双引号（""）中。
description成员的访问的说明。
标记使您得以将成员的访问记入文档。
System.Security.PermissionSet使您得以指定对成员的访问。
description
description：
备注说明。
标记是可以描述有关类或其他类型的备注概述信息。
3.2.4注释规范
3.2.4.1代码文件注释
对于每一个代码文件（*.cs），在文件起始位置添加注释，用以声明该代码文件的用途、版本修订历史、作者、创建日期以及版权声明等信息。
3.2.4.2类型定义注释
升级会员 