程序设计规范文档.doc

1、商汇系统 - 程序设计规范文档简述：1， 所有名字统一通过对英文的缩写或者组合来表达。(注：UCP 是 Unified Communication Platform 的缩写 )，数据库操作使用存储过程，客户端代码请使用 JQuery 或者.NET AJAX 框架来实现，文本均需写进资源文件里边，module 的样式尽量使用 dotnetnuk 的default.css 中已经定义的，如须使用自己的样式文件，请在本 module 的根目录下建立module.css 文件，并将样式定义放入其中，样式定义命名规则如 附录四：CSS 类及id 中的命名规则2， 目录结构要求按照 dotnetnuke

2、Module 的目录结构要求规范化，如：资源文件放到本Module 的子目录 App_LocalResources 下，资源文件名为对应 ascx 名称+”.”+zh-cn.resx，逻辑代码应该规范在逻辑层文件中（ CBO，Controller，Centralized Custom Business Object Hydration） ，数据库访问层以 Provider 的设计模式实现，表现层要求实现样式和内容分离，提示性字符串要求写到资源文件中。3， Module 间需要做到独立性强，Module 间的联系尽量通过配置的方式来实现。4， 名字空间（Namespace）规则，名字空间的命名规

3、则遵循 DNN 对 module 的命名规则，采用公司名称（或者项目名称）+“.” +Modules + “.” + 模块名 + “.” + 功能名例如个人资料 Module 的名字空间（Namespace）的命名规则如下：UCP.Modules.Profile.EditProfileUCP.Modules.Profile.ViewProfileUCP.Modules.Profile.Settings5， 其它 module 请参考该命名规则a) 程序集命名规则为避免代码冲突, 现将本系统程序集名称规范如下。例如个人资料 Module 的程序集名称为：UCP.Modules.Profile.d

4、ll.b) 类，变量、方法、以及属性类，量、方法和属性的名称的第一个字母须大写，并且名称应该能表达出它们的用途（或者说是意义） 。如：变量“员工名称” ，其在程序中的变量名称须为：EmployeeName，变量“字节数” ，其在程序中的名称须为：NumberOfBytes 等等。方法“添加数据”的名称须为：AddData （） ，动词（Add）+动词对象名称（Data ）c) 数据库表名以及存储过程命名规范数据库对象包括表、视图（查询） 、存储过程（参数查询） 、函数、约束。对象名字由项目名前缀，对象类型名和实际名字组成，长度不超过 30。前缀和对象类型名：使用小写字母。本项目数据库对象表名由

5、 “模块名” + “_”+ 本表的业务名，如表的业务名称与模块名称一致，用模块名即可，如个人资料表名称为“Profile” ，存储过程的命名由动词+动词对象名称，如：AddProfile， DeleteProfile，GetProfile， UpdateProfiled) CSS 类及 id 的规范化命名根据在文档中的使用目的来对类以及 id 进行结构化命名，详细情况e) 未尽事宜请参考如下附录和http:/ dotnetnuke 的相关命名规则。6， 附录：附录一：.NET 中的命名规则附录二：网站文件命名规则附录三：数据库中的命名规则附录四：CSS 类及 id 中的命名规则附录一：.NET

6、 中的命名规则名称空间的命名 命名名称空间的一般规则如下： CompanyName.TechnologyName这样，我们看到的名称空间应该是这样的： Microsoft.OfficePowerSoft.PowerBuilder 注意：这只是一个原则。第三方公司可以选择其它的名字。避免用公司名称或其它著名品牌的名称作为名称空间的前缀，这样会造成两个公布的名称空间有同一个名称的可能性。例如： 将微软提供的 Office 自动类命名为 Microsoft.Office使用 Pascal 大写方式，用逗号分隔逻辑成分。例如：Microsoft.Office.PowerPoint如果你的品牌使用的是非

7、传统大写方式，那么一定要遵循你的品牌所确定使用的大写方式，即使这种方式背离了通常的名称空间大写规则。例如：NeXT.WebObjectsee.cummings类和类成分的命名类的命名原则是用名词或名词短语命名类，使用 Pascal 大写。减少类名中缩写的使用量。不要使用任何类前缀（比如 C），不要使用带下划线的字符。例如：public class FileStream public class Button public class String 变量的命名名称中各单词首字母均为大写。例如：FindLastRecordRedrawMyForm在内部范围中避免使用与外部范围中的名称相同的名称。若

8、访问错误变量，则会产生错误结果。若变量与同一名称的关键字冲突，则必须在关键字前加适当的类型库以作标识。 例如：若有一个名为 date 的变量，只能通过调用 System.Date 来使用内部 Date 函数。 函数和方法的命名函数和方法的命名应该以动词开始，使用 Pascal 大写。不要使用带下划线的字符。例如：InitNameArrayCloseDialog接口命名原则使用名词或名词短语，或者描述行为的形容词来命名接口,使用 Pascal 大写。 减少接口名中缩写的使用量，在接口名前加前缀 I，以表示这个类型是一个接口。例如： IComponent（描述性名词）ICustomAttribut

9、eProvider（名词短语）IPersistable（形容词）参数的命名 使用描述性参数名。参数名应该具有足够的描述性，这样在大多数情况下参数名和它的种类可以用来确定它的意思。根据参数的意思来命名参数，而不是根据参数的种类来命名。我们希望开发工具可以用很方便的方式提供关于参数种类的信息，这样参数名可以得到更好的使用，可以对语义而不是对种类进行描述。但是偶尔使用根据类型命名的参数名也是完全可以的。不要使用保留参数。如果在下一个版本中需要更多的数据，可以增加进来。例如：Type GetType (string typeName)string Format (string format, obje

10、ct args) 属性的命名用名词或名词短语命名属性，属性与类型要一样。 用与一个类型的名称相同的名字来命名属性时，就使这个属性的类型成为那个类型。虽然听起来有些奇怪，但这是正确的。 例如：public enum Color .public class Control public Color Color get . set .事件的命名用 EventHandloer 后缀命名事件处理程序，使用名为 sender 和 e 的两个参数，Sender 参数代表提出事件的对象。Sender 参数永远是一个类型对象，即使它可能使用了更为特定的类型，与事件相关的状态被封装在一个名为 e 的事件类范例中。

11、要使用这个类型的正确的、特定的事件类。 例如：public delegate void MouseEventHandler(object sender, MouseEvent e);命名事件名时，需要有之前和之后的时态概念，因此要使用现在时态和过去时态（不要使用BeforeXxxAfterXxx 的方式）。例如，可以被取消的结束事件就有 Closing 事件和 Closed 事件。 长项和常用项的命名可使用缩写使名称长度适中，通常，多于 32 个字符的变量名在低分辨率的监视器上难以阅读。同时，请确保缩写在整个应用程序中保持一致。 例如：可以使用“HTML”代替“HyperText Markup

12、 Language”。代码书写格式规范o 文件之中不得存在无规则的空行，比如说连续十个空行。一般来讲函数与函数之间的空行为 2-3 行。 o 在函数体内部，在逻辑上独立的两个函数块可适当空行，一般为 1-2 行。 o 每行长度尽量避免超过屏幕宽度，应不超过 80 个字符。 o 尽量用公共过程或子程序去代替重复的功能代码段。 o 使用括号清晰地表达算术表达式和逻辑表达式的运算顺序。如将 x=a*b/c*d 写成 x=(a*b/c)*d 可避免阅读者误解为 x=(a*b)/(c*d)。 o 避免采用过于复杂的条件测试。 o 避免过多的循环嵌套和条件嵌套。 o 一个函数不要超过 200 行。一个文件

13、应避免超过 2000 行。 o 避免使用 goto 语句。 o 避免采用多赋值语句，如 x = y = z;。 代码注释规范.cs 文件的注释所有.cs 文件开头都要加上注释，写明文件创建时间、作者、用途概述等例如： /*/新增日期:2004.7.19/作者:XXX /內容说明: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/*函数过程注释所有的函数体开头都要加上注释，所以注释使用.NET 注释规范。例如： / / 构造函数/ / 示例参数 1/ 示例参数 2public UpgradeThread(string is_xxx1, string is_xxx2)/常量变量

14、注释所有的常量变量，无论是全局还是局部使用的，凡是对代码整体起到关键性做用的都需要加上注释。例如： / / 当前线程指向的备份文件本地保存路径/ public string StorePath = ;代码修改注释当开发者维护以前的程序代码时，需要在修改处的开始及结尾，加上自己的注释信息。例如： /BEGIN 2004-7-19 Jayson 修正了 XXX 问题略/END 2004-7-19 Jayson附录二：网站文件命名规则 关于文件的命名，看似无足重轻，但实际上如果没有良好的命名规则进行必要的约束，一味的乱起名称，最终导致的结果就是整个网站或是文件夹无法管理。所以，命名规则在这里同样非常

15、重要。 需要特别注意的时候，网站文件或文件夹命名请尽量避免使用中文字符命名。文件的命名 以最少的字母达到最容易理解的意义。 索引文件统一使用 index.html 文件名(小写) index.html 文件统一作为“桥页“，不制作具体内容，仅仅作为跳转页和 meta 标签页。主内容页为 main.html。按菜单名的英语翻译取单一单词为名称。所有单英文单词文件名都必须为小写，所有组合英文单词文件名第二个起第一个字母大写； 所有文件名字母间连线都为下划线。例如： 关于我们 aboutus 信息反馈 feedback 产 品 product 图片的命名以图片英语字母为名。以最少的字母达到最容易理解

16、的意义。 对于较小的图片，我们使用如下格式的命名 ：sm.kahn.gif其中，sm 代表“small”，kahn 代表图片的内容。较大图像的命名规则也一样，不过是以 bg 开头的：bg.kahn.gif用以区分不同图像的命名规则应当是全站通用的，这样可以尽量避免将不同的名称搅混。网站目录的命名目录建立的原则是以最少的层次提供最清晰简便的访问结构。服务器的 ftp 上传目录默认为 html 根目录文件 根目录只允许存放 index.html 和 main.html 文件，以及其他必须的系统文件。每个语言版本存放于独立的目录。已有版本语言设置为： 简体中文 gb 繁体中文 big5 英 语 en

17、 日 语 jp 每个主要功能(主菜单)建立一个相应的独立目录。 根目录下的 images 为存放公用图片目录，每个目录下私有图片存放于各自独立 images 目录. 例如： menu1images menu2images另外，所有的 js 文件存放在根目录下统一目录script 所有的 CSS 文件存放在根目录下的 style 目录 所有的 CGI 程序存放在根目录并列目录cgi_bin 目录。对于一些信息更新量比较大的站点或是栏目，还可以采用一种更为特殊的方式来进行文件架的命名，这样能使得日后的维护更加方便，这样的方式就是使用“单一单词命名的目录”+“年年年年_月月_日日”的方式命名，最后的

18、“日日”是根据更新量大小可选择的，如果每日更新量很大则可以加上“日日”。例如： news2005_08news2005_09 news2005_10_12 附录三：数据库中的命名规则数据库涉及字符规则采用 26 个英文字母（区分大小写）和 0 9 这十个自然数，加上下划线_组成，共 63 个字符。不能出现其他字符（注释除外）。据库对象命名规则数据库对象包括表、视图（查询）、存储过程（参数查询）、函数、约束。对象名字由前缀和实际名字组成，长度不超过 30。前缀：使用小写字母。例如：实际名字实际名字尽量描述实体的内容，由单词或单词组合，每个单词的首字母大写，其他字母小写，不以数字和_开头。例如：表

19、 UserInfo视图 UserListVi存储过程 DeleteUser因此，合法的对象名字类似如下。表 Message、UserInfo、MessageDetail视图 MessageListVi存储过程 AddMessage字段命名规则数字、字符、日期/时间、lob(大对象)、杂项，字段由表的简称、下划线，实际名字加后缀组成。后缀：使用小写字母，代表该字段的属性。例如: UserIdintUserNamestrUserRegDatedtm视图命名规则字段由前缀和实际名字组成，中间用下划线连接。前缀：使用小写字母 Vi，表示视图。例如：UserViUserInfoVi存储过程命名规则字段由

20、前缀和实际名字组成，中间用下划线连接。前缀：使用小写字母 sp，表示存储过程。例如： GetUser数据库设计文档规则所有数据库设计要写成文档，文档以模块化形式表达。大致格式如下：- 表名： UserInfo 建立人：UAM_Richard 日期： 2004-12-17 版本： 1.0 描述： 保存用户资料 具体内容： UserIdint int，自动增量 用户代码 UserNamestr char(12) 用户名字 .-sql 语句规则所有 sql 关键词全部大写，比如 SELECT,UPDATE,FROM,ORDER,BY 等。附录四：CSS 类及 id 中的命名规则Web 开发人员可以通

21、过创建 CSS 类及 id 名称并使用这些名称来对 divs 以及其他的格式页面元素进行标识。对开发人员来说，在命名重新定义 XHTML 标记（tags）的 CSS selectors 时，必须保证其与预定义的标记准确匹配，但就类以及 id 选择器名称而言，则仁者见仁，智者见智。然而随心所欲的为这些类以及 id 命名则并不是个好的习惯。直观命名 当在设计 Web 页面以及需要对一个 div 进行标识的时候，最自然的想法就是使用可以描述元素所在页面位置的词汇来对其命名。例如：top-panelhorizontal-navleft-sidecenter-columnright-col这些是 CSS

22、 以及 XHTML 类和 id 的有效命名方式。这些词汇简单并且能够使人顾名思义，因此满足了标识页面元素以及相应的 CSS 样式的需要。但问题是这样的名称同页面内容的特定表达方式相关联。这些命名参考了某种特定页面布局中的页面元素位置，因此在这样的布局之外使用就会显得不合适甚至造成理解混乱。这些命名没有涉及文档内容的结构。因此，下面给出了对 CSS 类以及 ID 命名更好的方法。结构化命名这些是 CSS 以及 XHTML 类和 id 的有效命名方式。这些词汇简单并且能够使人顾名思义，因此满足了标识页面元素以及相应的 CSS 样式的需要。 这些是 CSS 以及 XHTML 类和 id 的有效命名方

23、式。这些词汇简单并且能够使人顾名思义，因此满足了标识页面元素以及相应的 CSS 样式的需要。有标记的相关信息都是用来描述文档的结构而不是外观。这样的特点使得我们可以通过简单的改变CSS 的方式来对不同外观格式下的内容（content）以及标记（markup）进行重用。当你理解这种方式时，很容易就可以发现采用页面位置来为类以及 id 命名的方式在处理如音频（audio）等外观格式上显得非常不合适。因此，应当根据在文档中的使用目的而非出现位置来对类以及 id 进行结构化命名。可以按照如下所示的结构化方式来对类以及 id 名称命名：例如：brandingmain-navsubnavmain-cont

24、entsidebar这些名字同直观命名方式一样非常易懂，但他们描述了页面元素的作用而非位置。这使得代码更加符合使用纯粹的结构化标记（structural markup）的初衷，即开发人员可以在不改变标记的情况下对各种各样媒体下的显示格式进行处理。即使你不打算在其他的媒体上对 Web 页面进行格式修改，使用结构化命名方式还可以帮助你在日后的站点升级或重新设计中更为轻松。例如，结构化命名避免了当一个 div 同 id right-column 移动到页面左边后所带来的混乱。对 div sidebar 的采用这样的命名方式就显得更加适当，因为无论它出现在页面的哪一边，这个名字仍然对开发人员来说直观易懂。惯例Andy Clarke 分析了 40 份由推崇标准化 Web 设计理念的开发人员所设计的 Web 站点的源代码。尽管类以及 id 名称很不统一，但是还是发现了一些频繁出现的常用名称。这里给出了最常用类/id 名称的示例列表：例如：headercontentnavsidebarfooter