1、JAVA 编 程 规 范JAVA 编程规范- i -目 录目 录 I1. 命名规则 .11.1 包与类命名 .11.1.1 包结构与类名前缀 .11.1.2 类命名 .11.2 变量命名 .21.2.1 简单数据类型 .21.2.2 类实例命名 .21.2.3 枚举数据常量 .31.3 类方法命名 .31.3.1 存取类型的类方法命名 .31.3.2 一般类型的类方法命名 .32. 源程序结构 .43. PACKAGE 区 .44. 系统 IMPORT 区 45. 用户 IMPORT 区 46. 类说明 .57. 类成员属性定义 .68. 类方法定义 .78.1 类方法说明 .78.2 类方法
2、实现部分编程规范 .88.2.1 程序注释的形式 .88.2.2 局部变量 .98.2.3 语句块 .98.2.4 条件判断ifelse 98.2.5 条件判断switchcasedefault .108.2.6 循环控制语句 .118.2.7 方法调用 .118.2.8 编程风格的要求 .129. 编写类和方法时的一些约定 .1510. 文档化 .1711. 附录 .1811.1 本系统常用单词表 .1811.2 参考资料 .19JAVA 编程规范- 1 -1. 命名规则1.1 包与类命名1.1.1 包结构与类名前缀为了便于管理Java开发的应用，Java开发的应用包命名要求带有前缀com，
3、采用“com.包名.子功能包名”的形式，如com.bcl表示基础工具包。在日常项目应用中积累的公共的内容希望能够形成通用的工具包，供项目组使用，工具包与应用包同级，采用“com.应用包名.子应用包名”的形式来组织项目开发的程序代码。包名和子功能包名要求具有实际的意义，从单词或缩写上能够看出包的意义，如 “com.bcl”表示基础工具组件的包，纳入公司的基础构件库进行管理，应用的包由项目组自己命名，命名的意义与具体的项目应用的意义相符。1.1.2 类命名(1) 类名首字母应该大写，字段、方法以及对象（句柄）的首字母应小写。对于所有标识符，其中包含的所有单词都应紧靠在一起，而且将中间单词的首字母大
4、写。例如：ThisIsAClassNamethisIsMethodOrFieldName若在定义中出现了常数初始化字符，则大写static final基本类型标识符中的所有字母。这样便可标志出它们属于编译期的常数。Java包（Package）属于一种特殊情况：它们全都是小写字母，即便中间的单词亦是如此。对于域名扩展名称，如com，org，net或者edu等，全部都应小写（这也是Java 1.1 和Java 1.2 的区别之一）。(2) 一行不要超过 80 个字符，并要注意折行时的写法。下面是例子：someMethod(longExpression1, longExpression2, long
5、Expression3, longExpression4, longExpression5);var = someMethod1(longExpression1,JAVA 编程规范- 2 -someMethod2(longExpression2,longExpression3); 1.2 变量命名（Attributes/Properties）在本规则中，变量表示一个类属性（Attribute/Property）或一个类方法中的变量。变量可以是简单数据类型，如整数或浮点数，也可以是一个对象，如客户帐户、操作员等。本变量命名规则还包括一类特殊的变量：枚举数据常量。1.2.1 简单数据类型循环计数器
6、在不影响程序可读性的前提下，可以使用传统的变量命名方式，如i、m、n等。除计数器以外的简单数据类型的变量由小写字母前缀+大写字母起头的英文单词（或单词缩写）组成。当然，循环计数器也可以使用这种命名方式，如nLoopCounter。数组在变量名前缀后加数组前缀“a”。简单数据类型前缀表：数据类型 变量名前缀 例子boolean b bCustomExist, baCustomExistchar c cSymbol, caSymbolsbyte y yByte, yaBytesshort s sHour, saHoursint n nLen, nLoopCounter, naLengthlong
7、l lMemory, laTimesfloat f fLength, faLengthdouble d dMile, daMiles注： byte 与 int 类型的前缀较特殊，使用时应注意1.2.2 类实例命名类实例采用以下两种命名方法：1对于可以使用单个单词表示并且该单词与类名一致（不含类名的前缀）的类实例，可以使用全部是小写字母的实例名。例如operator（类WFOperator的实例）、task（类WFTask的实例）、date（类Date的实例）。2其它情况下使用以小写字母表示的类名（也可以是类名的缩写）和以大写字母起始的名称组成的标识名。例如JAVA 编程规范- 3 -strOp
8、eratorName、dateStart、customerList。常用的类名缩写如下表：类 类名缩写 例子Exception e e, eAllExceptionSSBusiException be be, beLowBalanceSSDbAccess dba dba, dbaManagement, dbaCIFSSLogiException le le, leInvalidValueString str strOperatorName, strAddressWFOperator op opCustomerManager, opDepartmentManager3类实例数组或集合的命名，可以
9、在前两种情况的基础上用单词的复数形式表示，如tasks、opDepartmentManagers，也可以在变量前面加前缀“some”表示，如someTask、someOperator。1.2.3 枚举数据常量枚举数据常量由表示枚举类型的前缀和常量名称组成。前缀全部由小写字母组成，名称使用大写字母起头的英文单词。例如交易类型的枚举常量命名如下：不明交易类型 requestUnknown菜单请求 requestMenuPrepare任务准备 requestTaskPrepare任务提交 requestTaskProcess提交 requestReverseProcess登录 requestLogi
10、n系统应用准备 requestSysAppPrepare系统应用提交 requestSysAppProcess1.3 类方法命名1.3.1 存取类型的类方法命名对于直接操作类属性的方法，命名使用前缀“get”、“is”和“set”表示存或取类属性，后跟大写字母起头的英文单词。示例如下：Field Type Gettername SetternamefirstName String getFirstName() setFirstName()address SurfaceAddress object getAddress() setAddress()persistent Boolean isPer
11、sistent() setPersistent()customerId Int getCustomerId() setCustomerId()orderItems Array of OrderItem objects getOrderItems() setOrderItems()1.3.2 一般类型的类方法命名使用“动词”+“名词短语”的命名格式，其中动词使用小写字母。例如JAVA 编程规范- 4 -invokeProduct()、analyseRiskItem()、openAccount()、refreshOutPutStream()等。2. 源程序结构源程序按以下结构进行组织：程序区 说明
12、Package 区 使用关键字“package”定义当前类的包系统 import 区用户 import 区类说明类成员属性定义类方法定义注意：为了便于使用文档工具自动生成程序文档，程序员必须严格遵守格式说明。3. Package区定义类所属的包，例如：package Main;4. 系统import区定义需要引入的系统资源，例如：import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;import javax.servlet.ServletException;impor
13、t java.io.IOException;import java.util.Vector;5. 用户import区定义需要引入的本系统内部的包，例如：import SS.*;import App.*;JAVA 编程规范- 5 -6. 类说明类说明使用如下格式：/* 类的详细说明* * author 类创建者姓名* author 其他作者姓名* version 1.00 9999/99/99 类创建者姓名* 9.99 9999/99/99 修改者姓名 修改内容说明* 9.99 9999/99/99 修改者姓名 修改内容说明* see 参考类 1* see 参考类 2*/格式说明：项目 规则 备
14、注起始行 /* 该行不允许再有其他内容说明行 * 说明内容 说明行中对该类的功能进行说明，可以有多个说明行作者行 * author 姓名 如果有多名作者，则分写几个作者行，类创建者在第一个作者行版本行 * version 1.00 9999/99/99 姓名 * 9.99 9999/99/99 姓名“version”为创建版本行。创建版本行的版本号固定为 1.00，日期采用“年/月/日”格式，后跟作者姓名，不止一人时中间以“，”分隔。“”为修改版本行。修改版本行必须紧跟创建版本行，可以有多个修改版本行。修改版本行的版本号使用“主版本号.次版本号”格式，并且在姓名之后说明此次修改涉及的内容，其他
15、要求与创建版本行的要求一致参考行 * see 参考内容列出供参考的类或类的方法与属性（使用格式“类名”列出参考类；使用格式“类名#方法或属性名”列出具体方法或属性名），可以有多个参考行结束行 */ 该行不允许再有其他内容描述格式 描述信息 将描述信息使用 括起来例子：/* 工作流管理子系统* * author 李昕* author 雷鸣JAVA 编程规范- 6 -* version 1.00 2001/8/30 李昕* 1.01 2001/9/3 李昕，雷鸣 优化 invokeProduct()方法* 1.02 2001/9/10 李昕 修改登录错误* see SSBusiException*
16、 see SSLogiException*/7. 类成员属性定义类成员属性定义分为说明与定义两部分。说明部分有三种方式，见下表：方式 规则 备注简单说明方式/* 说明内容 */属性定义对于功能比较单一的类属性，使用简单方式进行说明。说明行以“/*”起头，以“ */”结束。定义紧跟在说明后，另起一行。详细说明方式/* 说明内容* */属性定义对于功能复杂，需要详细说明的类成员属性，使用详细方式进行解释。详细说明部分第一行必须是“/* ”，不能有其它内容；中间的说明行以“ * ”起头，后跟说明内容；结束行必须是“ */”，也不能有其它内容。定义紧跟在说明后，另起一行。枚举类型说明方式 /* 说明内
17、容 */ 属性定义对于定义的枚举类型（包括常量）的类属性，其定义放在说明部分之后，处于同一行上。对于枚举类型，说明内容的格式为“枚举类型-内容说明”。简单说明方式的例子：/* 提示信息 */private String strMsg = null;详细说明方式的例子：/* 详细的补充信息，此属性在缺省方式下不填，* 需要时通过 addDetail(String strDetailMessage)方法补充*/private String strDetail = null;枚举类型（常量）说明方式的例子：/* 标记-格式 */ public static final String tagMessa
18、geFormat = “MF“;/* 标记-交易类型 */ public static final String tagRequestType = “RT“;/* 标记-工作流 ID */ public static final String tagWorkflowId = “WF“;/* 标记-子任务 ID */ public static final String tagSubtaskId = “ST“;/* 标记-操作员 ID */ public static final String tagOperatorId = “OP“;/* 标记-口令 */ public static fina
19、l String tagPassword = “PW“;JAVA 编程规范- 7 -8. 类方法定义类方法定义有方法说明与方法实现两部分，方法实现部分必须紧跟在方法说明部分下一行。8.1 类方法说明类方法说明使用如下格式：/* * 类方法的详细使用说明* param 参数 1 参数 1 的使用说明* param 参数 2 参数 2 的使用说明* param 参数 3 参数 3 的使用说明* return 返回结果的说明* throws 异常类型.错误代码 注明从此类方法中抛出异常的说明* throws 异常类型 注明原来从此类方法的被调用方法中抛出的异常* see 参考类 1* see 参考类
20、 2#类方法或类属性*/格式说明：项目 类型 规则 备注起始行 必选 /* 该行不允许再有其它内容说明行 必选 * 说明内容 说明行中对该方法的功能进行说明，可以有多个说明行参数行 可选 * param 参数 参数说明一行对一个参数进行说明，可以有多个参数行。如果该方法没有任何参数，此项可省略。返回行 可选 * return 返回结果说明对方法的返回结果进行详细说明，只允许有一个返回行，但是可以折行。如果该方法没有返回，此项可省略。直接引发行 可选* throws 异常.代码 抛出* 说明一行对一类异常的一种错误码进行说明，可以有多个直接引发行。代码使用系统预定义的代码常量，不能直接写数字。列
21、出该方法直接抛出的异常，并说明在何种情况下抛出该异常。间接引发行 可选 * throws 异常 说明抛出者一行对一类异常进行说明，可以有多个间接引发行。列出该方法调用的方法可能抛出的异常。JAVA 编程规范- 8 -参考行 可选 * see 参考内容列出供参考的类或类的方法与属性（使用格式“类名”列出参考类；使用格式“类名#方法或属性名”列出具体方法或属性名），可以有多个参考行项目 类型 规则 备注结束行 可选 */ 该行不允许再有其他内容例子/* * 调用相关产品的指定方法* param request 请求参数* param ac 环境参数* param strProductMethod
22、产品方法名* return 应用处理结果* throws SSLogiException.codeNoEnoughParam 没有合适的方法或参* 数不足时抛出异常* throws SqlException MainScheduler.CallProduct()抛出* see AppContext* see AppOutput#form* see SSLogiException* see SqlException*/public abstract AppOutput invokeProduct(HttpServletRequest req,AppContext ac,String strPro
23、ductMethod)throws SSLogiException,SqlException;8.2 类方法实现部分编程规范8.2.1 程序注释的形式本系统中，程序注释分以下三种形式： 详细说明式：较详细地解释后续处理的功能、算法等内容，可以有多行说明。/* 说明内容* */程序行 简单说明式：简要说明后续处理，注释内容在一行内写完。JAVA 编程规范- 9 -/* 说明内容 */程序行 行末说明式：紧接在一个程序行最右边，对该行程序进行简要说明，注释内容在一行内写完。程序行; /注释内容8.2.2 局部变量原则上，一行中只允许定义一种类型的同一种用途的变量。局部变量定义必须在同一行定义语句后
24、面加以注释，使用行末说明式的注释方法。一个变量只能用于一种用途。例如用于循环计数的变量就不要再用作记录函数的返回值。变量注释举例如下：int i, n; /循环计数器int nPromptMsgLength; /提示信息长度WFOperator operator; /当前操作员WFOperator opDepartmentManager; /当前部门主管8.2.3 语句块完成一种功能的一组语句组成一个语句块。语句块之间应该使用空行适当分隔。在语句块前面必须加注释，详细说明其后的语句块的功能。注释采用详细说明或简单说明的注释形式。/* 功能说明一*/语句语句（空行以分隔两个功能的语句块）/* 功
25、能说明二*/语句语句在语句块的注释中，必须包括详细设计文档中的所有伪码，以标明此段程序是在实现哪部分详细设计。JAVA 编程规范- 10 -8.2.4 条件判断 ifelse每一个条件判断语句前面使用详细说明或简单说明形式进行注释，在每一个分支内或者使用详细/简单说明形式进行注释，或者在条件分支语句后面以行末说明形式进行注释。例如在条件分支内进行注释：/* 判断说明*/if ()/* 处理说明*/ else/* 处理说明*/ 或者在条件分支语句末进行注释：/* 判断说明*/if () /处理说明 else /处理说明 8.2.5 条件判断 switchcasedefault与if式的判断语句类
26、似，在每一个条件判断语句前面使用详细说明或简单说明形式进行注释，在每一个分支内或者使用详细/简单说明形式进行注释，或者在条件分支语句后面以行末说明形式进行注释。例如在条件分支内进行注释：/* 判断说明*/JAVA 编程规范- 11 -switch ()case :/* 处理说明*/ break; default:/* 处理说明*/ 或者在条件分支语句末进行注释：/* 判断说明*/switch ()case : /处理说明 break; default: /处理说明 8.2.6 循环控制语句循环语句块前必须使用详细说明或简单说明形式进行注释说明，在循环体内部的每一条循环控制语句或者使用详细/简单
27、说明形式进行注释，或者使用行末说明形式进行注释说明。例如：/* 循环处理说明*/for (;) break; /退出循环说明（如何种条件下退出循环） continue; /循环控制条件说明 JAVA 编程规范- 12 -8.2.7 方法调用在每一个方法调用前使用详细说明或简单说明形式进行注释，解释调用该方法的目的。例如：/* 使用得到的方法名调用合适的应用功能*/output = invokeProduct(request, ac, strMethodName);8.2.8 编程风格的要求1大括号（“ ”与“ ”）的使用类定义中使用起止括号均左边齐头的大括号，例如：public Class D
28、atetime类成员方法的实现部分，可以选择以下两种方式中的一种：起止括号均左边齐头或者起始括号在同一程序行尾部，终止括号左边齐头的格式，例如：/* 方法原型部分较短时，使用下面的格式*/public double getBalance() throws SSLogiExceptionif(dBalance 向缓冲池中增加一个属性和相应的字符串值* return int* param attribute java.lang.String* param data java.lang.String* exception java.lang.Exception*/ 描述信息使用 括起来，返回参数、传
29、入参数、异常处理进行申明。JAVA 编程规范- 18 -11. 附录11.1 本系统常用单词表单词 词意 建议的缩写Analysis 分析Class 类Client 客户端Component 组件，业务组件Customer 客户Date 日期Department 部门，处，室DepartmentManager 部门主管 dpmId 标识Length 长度 lenManager 主管Message 消息，信息 msgMethod 方法，操作，成员函数Object 对象Offset 偏移量 offOperator 操作员，柜员 opPassword 口令Phase 阶段Product 产品，金融产
30、品ProductPackage 产品包 ppkPrompt 提示Risk 风险Subtask 子任务Symbol 标识符，记号Task 任务Time 时间Workdate 工作日 wdtWorkflow 工作流 wflJAVA 编程规范- 19 -11.2 参考资料1 Scott W. Ambler.Writing Robust Java Code - The AmbySoft Inc. Coding Standards for Java.v17.01d.2 Silver Siu.The Java Coding Standard.Version 1.1.3 Sun Microsystems, Inc.How to Write Doc Comments for the Javadoc(TM) Tool.
