Net开发规范设计方案.doc

.net 开发规范目录1. 概述 .42. 命名规范 .42.1 指导性原则 .42.1.1 使用正确的大小写风格 .42.1.2 使用描述性英文名称 .42.1.3 使用易读的名称 .42.1.4 尽量避免在名称中使用编码 .52.1.5 同义词中使用固定的单词 .52.1.6 保持词义的前后一致 .52.1.7 名词和动词的选用 .52.1.8 使用计算机专业术语 .52.1.9 必要时可使用业务术语 .62.1.10 避免误导 .62.1.11 名词需要语境说明 .62.1.12 不要添加人为的语境 .62.1.13 避免名称差别不明显造成混淆 .62.2 大写风格 .62.2.1 Pascal 风格 .72.2.2 Camel 风格 .72.2.3 大写风格 .72.2.4 大写小结 .72.3 单词选择 .82.3.1 缩写 .82.4 命名空间 .92.5 类和类成员 .92.5.1 类的命名指南 .92.5.2 Attribute 命名指南 .102.5.3 枚举命名指南 .102.5.4 静态类属性名 .102.5.5 参数名 .102.5.6 方法命名指南 .112.5.7 属性命名指南 .112.5.8 事件命名指南 .112.6 大小写敏感 .123. 程序注释规范 .123.1 注释编写准则 .123.2 模块注释 .133.3 类的注释 .133.4 类成员方法的注释 .153.5 类成员属性、常量、变量的注释 .163.6 程序注释 .164. 代码书写规范 .164.1 排版规范 .165. 类成员使用规范 .205.1 属性使用指南 .205.1.1 只读和只写的属性 .225.2 事件使用指南 .225.3 方法使用指南 .235.3.1 方法重载指南 .235.4 构建函数使用指南 .245.5 类的成员变量使用指南 .255.6 参数名称指南 .266. 类型使用指南 .276.1 类使用指南 .276.1.1 基类使用指南 .276.2 值类型使用指南 .286.2.1 结构使用指南 .286.2.2 枚举使用指南 .286.3 程序代理使用指南 .306.4 程序属性(ATTRIBUTE)的使用 .307. 异常的产生和处理 .307.1 标准异常类型 .337.2 异常的包装 WRAPPING EXCEPTIONS .348. 数组使用指南 .348.1 数组 VS. 集合 .348.1.1 集合 .348.1.2 集合中可索引的属性 .348.1.3 数组值属性 .358.2 返回空数组 .359. 数据库设计开发规范 .359.1 命名规范 .359.2 字段设计要求 .369.3 视图使用原则 .369.4 存储过程建立规则 .369.5 函数建立规则 .369.6 触发器使用要求 .361 概述在建设过程中，将涉及到在新的 Visual Studio.NET 以及 .NET Framework 平台上的开发工作。同时，设计人员、开发人员和测试人员较多。为了使应用程序的结构和编码风格标准化，便于阅读和理解编码，以提高开发效率和产品的标准化，制订一套开发规范和标准势在必行。此外，好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约定相一致，并且尽可能的直观。希望开发人员严格遵守此套开发规范和标准，并落实到自己的程序中。一组通用目的的编码约定应该定义完成上述目的所必需的、能让程序员自由地创建程序逻辑和功能流程的最小的要求。最小编码约定的目的是使程序易于阅读和理解，从而指导程序员更好地完成开发任务。本规范主要针对使用 Visual Studio.NET 以及.NET Framework 开发的基于 Web 的应用系统。2 命名规范2.1 指导性原则命名是编程的核心。能够对变量和函数/过程进行表意清晰而准确的命名，就能使程序的可读性大大提高，达到不说自明的效果。真正的名称是深入认真思考一个对象的生态环境后才能给出的。程序设计人员只有在充分理解并把握整个系统时，才可能给出真正合适的名字。如果名称选用恰当，一切就显得很自然，各部分关系清晰，意义可以推导而出，阅读程序时可以按常识推理，从而减小程序员对已有程序的阅读和理解困难，提高工作效率，使新程序员能在尽量短的时间内进入角色。以下章节描述了程序命名的一些指导性原则。2.1.1 使用正确的大小写风格为保证良好的程序可读性，对命名的大小写必须按照一致的规定编写，主要包括Pascal 风格和 Camel 风格两种，下面将会有专门的章节进行详细说明。2.1.2 使用描述性英文名称为保证程序的可读性，要采用准确描述其意义的名字。英语是国际通用语言，绝大多数商业类库或函数库代码都是由英语编写的。要与标准接轨，充分利用网上的程序资源，应尽量使用英语命名。2.1.3 使用易读的名称如果不可读或不易读，则不便于讨论和交流。因此我们要尽量使用大众化名称，避免使用不常用的单词。2.1.4 尽量避免在名称中使用编码对名称使用编码就需解码才能理解。少数几个前缀字母有助于区分名称类别。但为了追求风格而过分使用前缀和后缀就会造成生涩难懂的名字。例如 SRD2T3。含有编码的名称一般都没有可读性。当然，任何编码，只要科学，时间久了都能被掌握。但是，掌握编码需要新成员的额外精力，增加了适应难度，因此应尽量避免。2.1.5 同义词中使用固定的单词首先，我们应尽量使用英语词汇，因为汉语拼音实际上也是一种名称编码，特别是使用拼音首字母，即使是懂汉语拼音的人也未必能理解。有了用英语命名的前提，我们还应该注意：一个抽象概念可能有多个表述同义词，选择一个，始终如一。如对同一动作，在不同类中选用不同的名称，比如，fetch, retrieve 和 get，那么，使用你的类从事编程的人就要多费很多精力去理解它们。也就是说，我们应该通过使用一致的名称，创建统一的编程接口，简化学习的难度。2.1.6 保持词义的前后一致多数词都有不止一个意思，但在同一个系统中，应始终保持同一个意思。这和前面的原则是相对应的。使用不同的词汇，使人联想不同的接口和/ 或操作。同样，使用同样的词汇，使人联想相同的接口和/ 或操作。如果我学过使用 DeviceManager:add(), 我就会期望可以使用 ProtocolManager:add(). 这是根据名称产生的联想，甚至连想到可以使用*Manager:add()。要保证这种联想能成立，前后词义必须一致。如果自己设计一个系统，要尽量做到保持词义的一致。记住，在两个完全不同的范畴内使用相同的名字是很不可取的。2.1.7 名词和动词的选用类和对象应当使用名词或名词短语命名。方法中强调过程用动词，返回值用名词。作为一名设计人员，可能不太在意这些命名的琐事。尝试使用你设计的类去编写一段用户程序，看看有多少别扭或混乱的地方，一定可以反过来有助你改进设计。2.1.8 使用计算机专业术语尽量使用约定成俗的惯用语、计算机科学术语、算法名称、设计模式名称、数学名词等软件编程相关名词。这样似乎有点异端，但这总好过让程序员费劲找客户弄清楚自己原本清楚的概念，只是由于名称的不同使他们疑惑。我们是讲编码规范，程序员大多数是计算机专业的，或对计算机专业已有了深入了解的。很少最终用户会阅读程序，即使有，也是有相当计算机软件功底的。相反，程序维护人员必须阅读程序，所以应尽可能使用计算机术语。如：运用工厂模式类的命名应该是“名词+Factory” 。2.1.9 必要时可使用业务术语如果工作的重点不在程序本身，或问题的描述比问题的解决更重要，可使用业务术语。在分析阶段，使用业务术语比使用计算机术语更好，因为容易被客户理解和接受。2.1.10 避免误导避免使用已有其它明确意义的名词。例如，“hp“, “aix“, 和 “sco“ 被用作 UNIX 平台及其变种的名称，如果再用来作为变量或函数名称就很有问题，会引起误解。即使你在解决的问题用 “hp“ 是很好的缩写也不应使用 “hp“。2.1.11 名词需要语境说明只有少数情况下，孤立的一个名字有明确含义。多数情况下，名称需要置于一定的语境中才有意义。比如，在类中，函数中或注释中。换句话说，在面向对象的语言中，在类属性的名称中包含类名是多余的。例如，不应该使用 Book.BookTitle，而应该使用 Book.Title 。Company. address_ 和 Customer. address_， 同样都是 address, 但仅在语境中才有意义，以下的命名是不可取的：Company. companyAddress_, Customer.customerAddress_。2.1.12 不要添加人为的语境不要在类的前面冠以公司名缩写、项目名称缩写或其他标志性前缀。例如，在做知识管理系统时，把员工类命名成 KmsUser。以上命名法是不可取的，这样势必造成代码重复，影响代码的重用。如使用同一个类，则 KmsUser 在其他系统中就显得不和谐了。2.1.13 避免名称差别不明显造成混淆这个问题源于编写程序仅仅是为了能编译通过或能解译执行。编译和解译程序不允许在同一域内用相同的名字指称两个东西。所以，遇到编译问题时，就随便将其中的一个改变一下。更糟糕的是，原本同一个名称，因拼写错误变成两个名称。这里要说的关键问题是，如果要区分两样不同的东西，一定要保证名称有实质性的差别。例如，若将一个类命名成 Product，另一个类命名成 ProductInfo 或 ProductData, 就会因差别不明显造成混淆。因为 Info 和 Data 没有具体的意思。同理，不要在 OO 编程中使用 Class 或 Object 作为名称的一部分。CustomerObject 和 Customer 有什么区别? NameString 比 Name 好吗? 难道一个 Name 还会是浮点数或整数不成？特别要强调的是，对于大小写敏感的编程环境，我们不要使用仅有大小写区别的名字。 例如，Customer, customer 不应作为两个名字。2.2 大写风格以下章节描述了不同方式的大写方式.这些术语将在通篇文档中被经常引用.2.2.1 Pascal 风格 这种风格大写每个单词的首字母BackColor应在所有由多单词组成的公共描述符中使用这种方式.举例而言,使用 TextColor 就比 Textcolor 或 Text_color 更好.注意不要大写 “连接词”（一个单词中包含了几个单词，但这个单词本身有自己的意思，如 Checkbook）每个组合单词的首字母。应该将这个单词作为一个单词来考虑，而非几个单词的组合。使用词典决定一个组合词是不是应该作为一个单词来使用。2.2.2 Camel 风格这种风格除了第一个单词的首字母,其他单词都应大写首字母,如下所示backColor在局部变量参数名或私有类属性名称上使用 camel 风格。 2.2.3 大写风格只在少于两个字母的缩写中使用大写。三个以上字母的缩写都应该使用 PASCAL 风格。举例而言 System.IOSystem.Web.UISystem.CodeDom一个另外的情形是和原有的未管理的标志兼容，而原来常用大写来表示枚举和常量。通常这些标志符不应该暴露给外部。2.2.4 大写小结下表描述了不同类型的描述符该怎么使用大小写类型 风格 备注Class Pascal 风格 Enumeration value Pascal 风格 Enumeration type Pascal 风格 Event Pascal 风格 Exception class Pascal 风格 用后缀 Exception.Read-only static field Pascal 风格 Interface Pascal 风格 用前缀 I.Method Pascal 风格 Namespace Pascal 风格 Property Pascal 风格 Public instance field Pascal 风格 很少使用，更多使用 properties. Protected instance field camel 风格 很少使用，更多使用 properties. Parameter camel 风格 2.3 单词选择不要使用常用的命名空间的名字做类名，举例而言不要使用以下任何单词做类名System Collections Forms UI不要使用和以下关键字冲突的识别符，举例而言，避免这样使用：AddHandler AddressOf Alias And AnsiAs Assembly Auto Base BooleanByRef Byte ByVal Call CaseCatch CBool CByte CChar CDateCDec CDbl Char CInt ClassCLng CObj Const CShort CSngCStr CType Date Decimal DeclareDefault Delegate Dim Do DoubleEach Else ElseIf End EnumErase Error Event Exit ExternalSourceFalse Finalize Finally FloatFor Friend Function Get GetTypeGoto Handles If Implements ImportsIn Inherits Integer Interface IsLet Lib Like Long LoopMe Mod Module MustInherit MustOverrideMyBase MyClass Namespace New NextNot Nothing NotInheritable NotOverridable ObjectOn Option Optional Or OverloadsOverridable Overrides ParamArray Preserve PrivateProperty Protected Public RaiseEvent ReadOnlyReDim Region REM RemoveHandler ResumeReturn Select Set Shadows SharedShort Single Static Step StopString Structure Sub SyncLock ThenThrow To True Try TypeOfUnicode Until volatile When WhileWith WithEvents WriteOnly Xor evalextends instanceof package var2.3.1 缩写1、请不要砍掉或抽取识别符的部分来作为名称使用。如使用 GetWindow 比 GetWin 更好.2、请不要使用使用不被广泛认可的缩写。 3、只有绝对需要时再使用广为人知的缩写。可以使用 UI 来表示 User Interface，用 OLAP来表示 On-line Analytical Processing.4、当使用缩写时，请使用 Pascal 风格或 camel 风格来表示超过两个或以上单词缩写的构成。如用 HtmlButton 而非 HTMLButton，但不要用 System.Io 来取代 System.IO2.4 命名空间以下模板举例说明了命名空间的命名规则。.Design因此我们希望看到这样如下命名空间:Microsoft.MediaMicrosoft.Media.DesignPowerSoft.PowerBuilder.Math 、 避免两个 PUBLISED 的 NAMESPACES 名称一样的可能。使用公司名称或者一个正式分支的名称如用 Microsoft.Office 来表示 Microsoft 提供的 Office Automation Classes。、 使用一个稳定的被广泛认可的技术名称作为第二层名称、 不要使用组织的结构层次作为命名空间的层次依据、 请在 DESIGN-TIME 命名空间前加上.Design 前缀以表示基础命名空间 DESIGN-TIME 特性。如 System.Windows.Forms.Design 包含了用来设计 System.Windows.Forms 应用程序的的设计器和相关设计类。、 使用 PASCAL 风格,把每个逻辑部件用分隔号分开(如 Microsoft.Office.PowerPoint _)如果你的品牌采用了非传统方式的命名,那么就延续的你的品牌的命名方式，就算他和通常的命名空间法则不同。如（NeXT.WebObjects, and ee.cummings