软件开发项目开发规范.doc

JAVA语言编程格式规范软件研发中心XX项目组201303V1.0目录1. 前言42. 试用范围43. JAVA命名规范43.1 公共约定43.2 Java文件、包43.3 类、接口命名规范43.4 方法命名规范43.5 常量53.6 变量和参数53.7 组件/部件53.8 集合53.9 神秘的数63.10 其他63.11 Java异常63.12 数组命名64. 书写格式规范64.1 缩进64.2 空格64.3 对齐64.4 空行74.5 注释75. 代码文件风格75.1 文件生成75.2 package/import75.3 文件头部注释75.4 存取方法85.5 构造函数95.6 克隆方法95.7 类方法95.8 main 方法106. 开发框架约定106.1 视图层编码约定：106.2 控制层编码约定：106.3 实体层编码约定：106.4 服务层编码约定：116.5 通用编码约定：116.6 数据库约定：111. 前言为确保系统源程序可读性，从而增强系统可维护性，兹制定下述编程规范，以规范系统各部分编程。系统继承的其它资源中的源程序也应按此规范作相应修改。2. 试用范围本文档将作为广州诚泰交通机电工程有限公司研发中心XX项目系统软件（JAVA语言）开发的编程格式规范。在系统的编码、测试及维护过程中，要求严格遵守。3. JAVA命名规范3.1 公共约定命名指系统中对源文件名、方法、目录、包、数据库表名、数据库字段等的命名。A. 系统所用的命名都使用英文缩写来表达。B. 命名的组成方式为：前缀+命名词素缩写，前缀表达出命名的用途，如数据库表等。C. 命名的前缀由项目组确定。D. 除系统公共维护对象外的其他对象，命名全部用小写。一种方式用“_”作连接符，另一种方式是词素的第一个字母大写直接连接在一起。在本规范中，数据库名、数据库字段名采用第一种方式，其余采用第二种方式。E. 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名F. 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。G. 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等，具体参看下表，严禁滥用缩写。H. 避免使用长名字（最好不超过35个字母）。I. 避免使用数字，但可用2代替to，用4代替for等，如：go2Jsp。3.2 Java文件、包A. 文件名当与其类严格相同，所有单词首字母大写。B. 包名一般以项目或模块名命名，少用缩写和长名，一律小写。C. 基本包：com.czpost，所有包、文件都从属于此包。包名按如下规则组成：基本包.项目名.模块名.子模块名. 如：com.czpost.eims;com.hepost.eims.untilD. 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。3.3 类、接口命名规范A. 所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。B. 接口可带I前缀。3.4 方法命名规范方法的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。法名称的第一个单词常常采用一个有强烈动作色彩的动词。取值类使用get前缀，设值类使用set前缀，判断类使用is(has)前缀。例：getName()setSarry()isLogon()方法参数建议顺序：(被操作者，操作内容，操作标志，其他) 例：public void replace(String sourceStr, String oldStr, String newStr) . 3.5 常量采用完整的英文大写单词，在词与词之间用下划线连接，如：DEFAULT_VALUE 3.6 变量和参数采用 直接定义的方法，要做到清晰易懂的原则，如：实体类 例如：Project project;直接把类型的首个大写字母变成小写字母就行了。日期型 例如：Date createDate;3.7 组件/部件应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则如：btnOK，lblName。A. 按钮变量 btn+Xxxxxxx 例如：btnSave,btnExit,btnPrint等B. 题标变量 lbl+Xxxxxxxx 例如：lblName,lblSex等C.对象类型 前缀CanvascvsCheckBox chkImageimgListlistChoicechcDialogdlgEventevtFramefrmMenumenuPanelpnlTextAreatxaTextField txf3.8 集合采用变量+集合类型的方法一个集合定义，如果集合采用泛型的话就必须泛型化处理如：Array userArray = new Array(); /用户列表Map userMap = new Map();/用户MapList onLineUserList = new List();/在线用户List3.9 神秘的数程序里经常会用到一些量，它是有特定的含义的，把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如50这个数，可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。3.10 其他命名时应使用复数来表示它们代表多值。如：orderItems。3.11 Java异常异常类名由表示该异常类型的单词和Exception组成，如ActionException。异常实例一般使用e、ex等，在多个异常时使用该异常名或简写加E，Ex等组成，如：SQLEx;ActionEx3.12 数组命名数组应该总是用下面的方式来命名：byte buffer;而不是byte buffer;4. 书写格式规范严格要求书写格式是为了使程序整齐美观、易于阅读、风格统一，程序员对规范书写的必要性要有明确认识。建议源程序使用eclipse工具开发，格式规范预先在工具中设置。4.1 缩进缩进建议以4个空格为单位。预处理语句、全局数据、标题、附加说明、函数说明、标号等均顶格书写。语句块的、配对对齐，并与其前一行对齐，语句块类的语句缩进建议每个、单独占一行，便于匹对。Mysclipse 中的默认方式是开始的不是单独一行，建议更改成上述格式。4.2 空格原则上变量、类、常量数据和函数在其类型，修饰名称之间适当空格并据情况对齐。关键字原则上空一格，如：if ( . ) 等。运算符的空格规定如下：:、-、+、-、!、+、-（指正负号）、&（引用）等几个运算符两边不加空格（其中单目运算符系指与操作数相连的一边），其它运算符（包括大多数二目运算符和三目运算符?:两边均加一空格，在作函数定义时还可据情况多空或不空格来对齐，但在函数实现时可以不用。,运算符只在其后空一格，需对齐时也可不空或多空格。不论是否有括号，对语句行后加的注释应用适当空格与语句隔开并尽可能对齐。个人认为此项可以依照个人习惯决定遵循与否。4.3 对齐原则上关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。另每一行的长度不应超过屏幕太多，必要时适当换行，换行时尽可能在,处或运算符处，换行后最好以运算符打头，并且以下各行均以该语句首行缩进，但该语句仍以首行的缩进为准，即如其下一行为“”应与首行对齐。变量定义最好通过添加空格或TAB键形成对齐，同一类型的变量最好放在一起。如下例所示：int nValue;int nResult;int nLength;4.4 空行不得存在无规则的空行，比如说连续十个空行。程序文件结构各部分之间空一行，由于每个函数还要有函数说明注释，故通常只需空一行或不空，但对于没有函数说明的情况至少应再空一行。对自己写的函数，建议也加上“/-”做分隔。函数内部数据与代码之间应空至少一行，代码中适当处应以空行空开，建议在代码中出现变量声明时，在其前空一行。类中四个“p”之间至少空一行，在其中的数据与函数之间也应空行。4.5 注释注释是软件可读性的具体体现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。程序注释不能用抽象的语言，类似于处理、循环这样的计算机抽象语言，要精确表达出程序的处理说明。避免每行程序都使用注释，可以在一段程序的前面加一段注释，具有明确的处理逻辑。注释必不可少，但也不应过多，不要被动的为写注释而写注释。以下是四种必要的注释：A. 标题、附加说明。B. 函数、类等的说明。对几乎每个函数都应有适当的说明，通常加在函数实现之前，在没有函数实现部分的情况下则加在函数原型前，其内容主要是函数的功能、目的、算法等说明，参数说明、返回值说明等，必要时还要有一些如特别的软硬件要求等说明。公用函数、公用类的声明必须由注解说明其使用方法和设计思路，当然选择恰当的命名格式能够帮助你把事情解释得更清楚。C. 在代码不明晰或不可移植处必须有一定的说明。D. 及少量的其它注释，如自定义变量的注释、代码书写时间等。5. 代码文件风格所有的 Java(*.java) 文件都必须遵守如下的样式规则：5.1 文件生成对于规范的 JAVA 派生类，尽量用 Myeclipse工具来生成文件格式，避免用手工制作的头文件/实现文件。5.2 package/importpackage 行要在 import 行之前，import 中标准的包名要在本地的包名之前，而且按照字母顺序排列。用到什么就导入什么包。减少采用 import 行中包含了同一个包中的不同子目录 * 来处理。 .stats;import java.io. InputStream;import java.io. OutputStream;importjava.util.Observable;importhotlava.util.Application;使用这里 import java.io. InputStream 和import java.io. OutputStream 来代替java.io.* 的。5.3 文件头部注释文件头部注释主要是表明该文件的一些信息，是程序的总体说明，可以增强程序的可读性和可维护性。文件头部注释一般位于 package/imports 语句之后，Class 描述之前。要求至少写出文件名、创建者、创建时间和内容描述。其格式应该尽量约束如下：/*Title: 确定鼠标位置类* Description: 确定鼠标当前在哪个作业栏位中并返回作业号* Copyright: Copyright (c) 2002* Company: HIT* author: rivershan* version: 1.0*/Class接下来的是类的注释，一般是用来解释类的。 /*A class representing a set of packet and byte counters* It is observable to allow it to be watched, but only* reports changes when the current set is complete*/接下来是类定义，包含了在不同的行的 extends 和 implements ，所有继承（扩展）全部写在一行，如：public class CounterSet extends Observable implementsCloneableClass Fields接下来是类的成员变量： /*Packet counters*/Protected int packets;public 的成员变量必须生成文档（JavaDoc）。proceted、private和 package 定义的成员变量如果名字含义明确的话，可以没有注释。5.4 存取方法接下来是类变量的存取的方法。它只是简单的用来将类的变量赋值获取值的话，可以简单的写在一行上。（个人认为尽量分行写）/*Get the counters* return an array containing the statistical data. This array has been* freshly allocated and can be modified by the caller.*/Public int getPackets() Return copyArray(packets, offset); public void setPackets(int packets)this.packets = packets;其它的方法不要写在一行上5.5 构造函数接下来是构造函数，它应该用递增的方式写（比如：参数多的写在后面）。 Public CounterSet(int size) this.size = size;5.6 克隆方法如果这个类是可以被克隆的，那么下一步就是 clone 方法： Public Object clone()try CounterSet obj = (CounterSet)super.clone();obj.packets = (int)packets.clone();obj.size = size;return obj; catch(CloneNotSupportedException e) throw new InternalError(Unexpected CloneNotSUpportedException: + e.getMessage(); 5.7 类方法下面开始写类的方法： /*Set the packet counters* (such as when restoring from a database)*/protected final void setArray(int r1, int r2, int r3, int r4) throwsIllegalArgumentException/ / Ensure the arrays are of equal size / if (r1.length != r2.length | r1.length != r3.length | r1.length != r4.length)throw new IllegalArgumentException(Arrays must be of the same size;System.arraycopy(r1, 0, r3, 0, r1.length);System.arraycopy(r2, 0, r4, 0, r1.length);5.8 main 方法如果main(String) 方法已经定义了, 那么它应该写在类的底部。6. 开发框架约定6.1 视图层编码约定：A. 考虑以后多语言的支持，jsp页面采用统一的UTF-8编码，不允许使gbk/gb2312。B. 采用统一定义的CSS风格，不允许使用自创风格。C. 统一使用页面校验方法。D. 每一个模块统一命名jsp页面名称：1) 首页：index.jsp2) 列表：list+实体名.jsp3) 显示：show+实体名.jsp4) 添加编辑：addEdit+实体名.jsp5) 提交：handle+实体名.jsp6) 打印：print+实体名+of+关键字（例如按月打印，关键字就是month）.jspE. 页面内容提示信息分为两种统一的约定：信息提示和错误提示：和F. 页面常用引入文件采用统一模版（由李煜慈统一规范）a. 所有页面，必须包含：1. 【放在html标签外】2. 【放在head标签中】3. 【放在body标签中的第一行】b. List页面，包含ecside列表1. 标签外必须加上和2. 对于表格的编辑查看的权限必须加上标签，用于控制这个是查看权限的标签，其它的如edit,remove3. 对于工具栏的操作权限，如：这个是添加权限，必须写在jQuery(function().);之中,而且callBack的函数必须在页面定义，否则就会出错。c. 左右结构带树形的页面（不能拖动）1. 初始化页面的大小：subLayoutInit()可以设置参数，设置左边的宽度，默认是250，2. 定义加载树的函数：loadTree(),创建树：treeTool = new TreeTool(subLeftTree, $ctxrms/road/roadinfo/getTree.action);3. 树的权限信息，treeTool.setOperatePrivilege();其中operates可以加入多个，但操作对应的处理函数必须定义，否则会出错，如addFn, 必须是fn来作为处理函数的后缀，可以参考ms/sys/constantdd/index.jsp页面d. 左右结构带树形的页面（能拖动），跟不能拖动树的不同是创建的函数不一样：var resourcesTree = jQuery.fn.zTree.init(jQuery(#subLeftTree), getDragDropSetting($ctxms/sys/role/getTree.action);treeTool = new DragDropTreeTool(resourcesTree);treeTool.setOperatePrivilege();/权限treeTool.init($ctxms/sys/role/nodeDropTree.action);/定义拖动请求的Actione. 标签1. 工具栏的操作权限标签ct:operatePrivilege生成按钮和绑定回调函数operate必选，操作callBack可选，回调函数，写入这个标签就必须写实现函数，否则报错备注：不能有标签体，如：XXXXXXXXXX2. 操作权限标签ct:privilegeoperate必选，操作备注：必须有标签体3. 树的操作权限标签ct:treeOperatePrivilege生成按钮和绑定回调函数，以fn作为后缀，如addFnoperate必选，操作，可以写入多个权限，以“,”隔开备注：不能有标签体4. 数据字典标签ct:constantDD 生成select下拉框codeValue必选，对应的数据字典的codeValueformName可选，select元素的name，默认与codeValue一样value可选，值extendFeatures可选，select元素的属性信息defaultValue可选，默认值isRead可选，是否可读，默认“false”valueColumn可选，值对应的列名称，默认是valuedisplayColumn可选，显示值的列名称，默认是name备注：不能有标签体5. 取得数据字典的显示信息ct:getConstanDDDisplayValuecodeValue必选，对应的数据字典的codeValuevalue必选，值valueColumn可选，值对应的列名称，默认是valuedisplayColumn可选，显示值的列名称，默认是name备注：不能有标签体6. 系统图标ct:iconInfo 生成select下拉框formName必选，select元素的namevalue可选，值extendFeatures可选，select元素的属性信息isRead可选，是否可读，默认“false”备注：不能有标签体7. 取得select下拉框ct:selectBeanclassName必选，对应的类formName必选，select元素的namedefaultValue可选，默认值extendFeatures可选，select元素的属性信息valueColumn可选，值对应的列名称，默认是iddisplayColumn可选，显示值的列名称，默认是namesortColumn可选，排序字段sortType可选，排序，默认升序isRead可选，是否可读，默认“false”备注：不能有标签体G. 控件使用jquery等（由李煜慈提供，讨论后决定）使用到js的全部使用jQuery关键字，不再使用$6.2 控制层编码约定：A. Action相关：1) Private static final Logger logger = Logger.getLogger(实体名称+Action.class);2) 必须继承3) 在引入service时，不再使用setter方法，使用Spring的注释方式Autowired4) 如果索引页不是listXX.jsp，addEditXX.jsp的不需要写方法，默认调用index.action,这个方法不需要写(在BaseAction)，只需要在配置文件写上这个Action,index可以重写，如果有需要的话.5) 如果需要生成树的信息的，用getTree.action6) 树拖动节点的，用nodeDropTree.actionB. Action中方法的命名与server中的方法，Xwork中的action的name，成功转发后的jsp页面的命名必须一致。例如：action中的listUsers()；server中的listUsers()；Xwork中的actionname= listUsers；成功跳转jsp页面listUsers.jspC. 所有Action类扩展（继承）自BaseAction例如：public class ProjInfoAction extends BaseAction6.3 实体层编码约定：A. 必须有无参数的构造方法B. 所有的实体类继承BaseModelC. 类属性命名与表字段名称相同、jsp页面表单域名字相同；如属性firstName对应的数据库字段firstName；如果字段是实体类的话采用实体类名称+Id的