《门户系统开发规范》由会员分享，可在线阅读，更多相关《门户系统开发规范（20页珍藏版）》请在金锄头文库上搜索。
1、门户产品开发规范开发规范 (提交稿)北京XXXX软件股份有限公司2009年4月文档说明本文档所涉及到的文字、图表等，仅限于北京XXXX软件股份有限公司内部使用，未经双方书面许可，请勿扩散到第三方。文档属性属性内容客户名称：XXXX软件股份有限公司项目名称：XXXX软件股份有限公司门户产品文档主题：门户产品开发规范文档编号：文档版本：0.1版本日期：2009-04-27文档状态：提交稿作者：XXXX文档变更版本修订日期修订人描述1.02009-04-27姜涛创建文档结构文档送呈单位姓名目的XXXX审阅XXXX参阅目 录(提交稿)11概述41.1最根本原则42程序设计标准52.1命名约定52.2注
2、释约定62.3快速浏览JavaDoc73门户系统开发规范93.1整体包结构说明93.1.1常用包结构103.1.2功能包结构113.2命名规则123.2.1共用类123.2.2业务层123.2.3展现层123.2.4模型层133.2.5持久层133.2.6XML配置133.2.7资源文件163.2.8事务命名约束173.2.9JS命名约束(待完善)171 概述本文提供一整套编写高效可靠的Java代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。而且，通过遵循这些程序设计标准，你作为一个Java软件开发者的生产效率会有显著提高。经验证明，若从一开始就花时间编
3、写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。1.1 最根本原则r 运用常识当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时侯： 运用常识并核实这些基本原则。这条规则比其它所有规则都重要。常识是必不可少的。2 程序设计标准Java的程序设计标准很重要，原因在于它将提高开发团队各成员的代码的一致性。一致性的提高会使代码更易理解，这意味着它更易开发和维护。从而降低了应用程序的总开发成本。你必须牢记的是：你的Java代码在你已离开并开始另一个项目之后，会保留相当长的一段时间。因此开发过
4、程中一个很重要的目标就是要确保在开发成员或开发团队之间的工作可以顺利交接，不必花很大的力气便能理解已编写的代码，以便继续维护和改进以前的工作。如果代码难以理解，很有可能被废弃和重写。2.1 命名约定我们将在整个标准中讨论命名约定，以下是几个基本点：r 使用可以准确说明变量/字段/类的完整的英文描述符例如，采用类似firstName，grandTotal 或 CorporateCustomer这样的名字。虽然象x1，y1或fn 这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。r 采用该领域的术语如果用户称他们的“客户” (client
5、s) 为“顾客” (customers)，那么就采用术语Customer 来命名这个类，而不用 Client。许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。r 采用大小写混合，提高名字的可读性一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。r 尽量少用缩写，但如果一定要使用，就要谨慎地使用这意味着应该保留一个标准缩写的列表，明智地从中选取，并且在使用时保持一致。例如，想对单词“number”采用缩写，那么可从 nbr，no 或者 num 中选取一个，说明一下采用了哪一个（具体是哪个倒无所谓），并且只使用这
6、一种形式。r 避免使用长名字（不超过15 个字母）虽然 PhysicalOrVirtualProductOrService 看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重新给它起个短一点的名字，比如象 Offering。 r 避免使用相似或者仅在大小写上有区别的名字例如，不应同时使用变量名 persistentObject和persistentObjects及anSqlDatabase和 anSQLDatabase这样的名称r 避免使用下划线作为名字的首末字母以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。更重要的是，下划线经常造成麻烦而且难输入，所以尽
7、量避免使用。2.2 注释约定本文还会对注释进行约定，以下是几个基本点： r 注释应该增加代码的清晰度代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。r 如果你的程序不值得注释，那么它也很可能也不值得运行 。r 保持注释的简洁最好的注释应该是简单明了的注释。注释不必洋洋洒洒，只需提供足够的信息，使别人能够理解你的代码。r 先写注释，后写代码写代码注释的最好方法是在写代码之前就写注释。这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗漏注释。另一种方法是边写代码边写注释。因为注释可以使代码更易理解，所以在程序开发的过程中，也可以利用这一点。如果打算花
8、些时间写注释，那么至少你应从这个过程中获得些什么。r 注释信息不仅要包括代码的功能，还应给出原因例如，下面例1中的代码显示金额在 $1,000 以上（包括 $1,000）的定单可给予 5% 的折扣。为什么要这样做呢？难道有一个商业法则规定大额定单可以得到折扣吗？这种给大额定单的特殊是有时限的呢，还是一直都这样？最初的程序设计者是否只是由于慷慨大度才这样做呢？除非它们在某个地方（或者是在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知道这些。2.3 快速浏览JavaDocSun 公司的 Java Development Kit (JDK) 中有一个名为 javadoc 的程序。它可
9、以处理 Java 的源代码文件，并且为 Java 程序产生 HTML 文件形式的外部注释文档。Javadoc 支持一定数目的标记，标识注释文档中各段起始位置的保留字。详情请参考 JDK javadoc 文档。标记用于目的author name类、接口说明特定某一段程序代码的作者。每一个作者各有一个标记。deprecated类、成员函数。说明该类的应用程序编程接口 (API) 已被废弃，因此应不再使用。exception name description成员函数说明由成员函数发出的异常。一个异常采用一个标记，并要给出异常的完整类名。param name description成员函数用来说明传递
10、给一个成员函数的参数，其中包括参数的类型/类和用法。每个参数各有一个标记。return description成员函数若成员函数有返回值，对该返回值进行说明。应说明返回值的类型/类和可能的用途。since类、成员函数说明自从有 JDK 1.1 以来，该项已存在了多长时间。see ClassName类、接口、成员函数、字段在文档中生成指向特定类的超文本链接。可以并且应该采用完全合法的类名。see ClassName#member functionName类、接口、成员函数、字段在文档中生成指向特定成员函数的超文本链接。可以并且应该采用完全合法的类名。version text类、接口说明特定一段代
11、码的版本信息。你注释代码的方式很大地影响着你的工作效率以及所有维护改进代码的后继开发者的工作效率。在软件开发过程中及早注释代码，会促使你在开始撰写代码之前仔细考虑这些代码，从而带来更高的工作效率。而且，当你重新阅读数天前或者数星期前所写的代码时，你可以很容易地判断出当时你是怎么想的，因为这一切都有记录。3 门户系统开发规范3.1 整体包结构说明目前UIP的大包结构如下：附图1. 包结构主要分5个包：1. askbar：问吧， 说明：存放了所有关于问吧的类包括 持久层，业务层，控制层和相应的模型。2. common：UIP平台的所有底层类和公共类。3. forum：论坛。4. framework
12、：UIP平台基本功能。说明：存放了所有关于UIP基本功能的类包括 持久层，业务层，控制层和相应的模型。5. im：即时消息。以上是UIP整体功能包结构的说明。注意：UIP是可扩展的平台，如果在新的功能增加将会与这5个包并其来命名。子包结构说明：公共包说明：附图2. 公共包结构以上是存放的是UIP整个平台的核心类，基本不做任何改动。主要分缓存，控制层基类，异常基类，过滤器，ldap，模型基类，wiki和常使用的类。各个模块功能包基本都一样就以问吧为例：附图3. 各个模块包结构所有功能的大模块都会按照这种层次结构来做，业务层，控制层，异常，模型，持久层，常用类。这里的常用类和公共里的不一样如果各大
13、模块在公共类里没有找到，可以在自己的模块中自行扩展。达到遵循“开闭”原则。3.1.1 常用包结构u cache包说明：所有的缓存结构。例如UIP所使用的OSCACHE。u config包说明：该包存放所有关于配置信息的类u util包说明：存放基本常用的类。例如文件类，字符串类等。u web包说明：存放在控制层下面的一些用于前端公用的类。例如登陆，登出，角色切换等。u constant包说明:存放常量类，比如全局类。u common包说明:存放所有公共的基本类，例如：控制层的公共类，持久层的公共类。u core包说明:存放关于平台里的核心类。例如平台的底层类。3.1.2 功能包结构按照各个层次
14、结构包分完：功能包基本分为2个包：1. 各个层次的接口包。2. 对于接口的实现包。3.2 命名规则3.2.1 共用类u 公共用类要求以“功能英文名称(首字母大写)”+ Util命名。例如：日期的英文名为date，按照规则要求，命名为：DateUtil ；u3.2.2 业务层u 业务层接口要求以 I +“模块英文名称(首字母大写)”+ Manager命名。例如：导航菜单的英文名为navigator，按照规则要求，命名为：INavigatorManager ；u 接口的实现类要求以“模块英文名称(首字母大写)”+ ManagerImpl 命名。例如：导航菜单的英文名为navigator，按照规则要
15、求，命名为：NavigatorManagerImpl ；3.2.3 展现层u 基类要求以“模块英文名称(首字母大写)”+ActionBase命名。例如：导航菜单的英文名为navigator，按照规则要求，命名为：NavigatorActionBase ；u 查询模块列表类要求以List +“模块英文名称(首字母大写)”+ s + Action命名。例如：导航菜单的英文名为navigator，按照规则要求，命名为：ListNavigatorsAction ；u 创建模块对象类要求以Create +“模块英文名称(首字母大写)”+ Action命名。例如：导航菜单的英文名为navigator，按照规则要求，命名为： CreateNavigatorAc
