Java编码规范

Java 编码规范

创建人 左培博 创建日期 2011-7-14 版本【Vx.x.x】 审核人/日期 最后修改日期

北京车讯互联息服务有限公司

1 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

修改记录

变更版本号

变更时间 修改人 变更摘要 2 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

目录

1

简介.......................................................................................................................... 4 1.1 1.2 1.3 1.4 1.5 2 3 4

目的 ............................................................................................................... 4 范围 ............................................................................................................... 4 定义、首字母缩写词和缩略语......................................................................... 4 规范等级说明 ................................................................................................. 4 参考文献 ........................................................................................................ 4

代码书写风格规范..................................................................................................... 4 命名规范................................................................................................................... 5 注释书写风格规范..................................................................................................... 5 4.1 4.2 4.3 4.4 4.5 4.6

注释总规则..................................................................................................... 5 类的注释 ........................................................................................................ 5 接口的注释..................................................................................................... 6 函数的注释..................................................................................................... 6 类属性的注释 ................................................................................................. 7 局部变量的注释.............................................................................................. 7

5 6 7 8

日志处理规范............................................................................................................ 7 异常处理规范............................................................................................................ 7 优化性能方面的建议 ................................................................................................. 8 附录.......................................................................................................................... 8 8.1 8.2

匈牙利命名法前缀对应表................................................................................ 8 常用动词表..................................................................................................... 9

3 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

1 简介

1.1 目的

为代码编写人员提供Java编码规范，提高编码质量，增强统一性，可读性，可维护性。

1.2 范围

涉众为Java开发过程中的各类人员，及相关学习人员

1.3 定义、首字母缩写词和缩略语 1.4 规范等级说明

  

级别I: 默认级别，要求所有项目中的所有成员遵守。 级别II: 建议所有项目中的所有成员遵守。 级别III: 鼓励各个项目根据实际情况执行。

1.5 参考文献

2 代码书写风格规范

   

删除所有的无用代码以及注释。

程序块要采用缩进风格编写，缩进的空格数为 4 个。 必须给程序加注释。注释能够极大提高代码的质量。 代码的书写必须清晰、易读。         

适当的将代码分段可以使代码更加清楚。可以使用‘{’‘}’将函数分成若干个小的单元；(II)

适当的加入空格或者空行可以使代码更加清晰。例如在函数的定义后面加入两个空行，在两个逻辑小代码单元间加入一个空行；

所有的判断和循环语句都必须用括号扩起来，并且在较长（超过一屏）的判断或者循环语句的结尾应该有注释语句做出标识。

建议遵循三十秒原则。如果另一个程序员无法在三十秒之内了解你的函数做了什么，如何做以及为什么要这样做，那就说明你的代码是难于维护的，必须得到提高；（II） 在一个函数内代码的长度不允许超过 150 行，超过 150 行的函数，建议在不破坏原有算法的基础上拆分为多个函数。（II）

程序中应用到的变量都需要在类或者方法的头部集中定义。 保证一行代码只做一件事。

使用圆括号来界定操作的顺序。避免使用默认优先级。

使用统一的格式化代码。将‘{’放在所有者的后面，并且在下一行代码前加入四个空格的缩进。

4 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

if(XXX) { while(XXX) {

xxx xxx } }

3 命名规范

 

各种标识符的命名要使用有实际意义的英文单词或英文单词的缩写，缩写要收录在该项目的简写词汇表中。切忌使用阿拉伯数字以及中文拼音进行命名。 在上一条的基础上，类名称要求大小写混写，首字母大写； 方法名称、局部变量名称要求大小写混写，首字母小写； 全局变量名称、常量名称要求全部大写。 

不允许出现名字隐藏，即局部变量、参数或者字段的名字，与另一个更大范围内定义的变量、参数或者字段的名字相同（或相似）。

4 注释书写风格规范

4.1 注释总规则

  

注释应该用中文清晰表达意思。应该能够使程序看起来更清晰，更容易理解。 注释要尽量简明，避免装饰性的、标语式的注释。

注释不但要说明做什么，还应当说明为什么要这样做。最好先写注释表明要做什么，再进行编码。

4.2 类的注释

    

类型的用途、目的。包括其它别人可能感兴趣的介绍；

已知的 Bug。当然最好是修正所有的错误，但是有时可能暂时还没有办法修正错误，或暂时没有时间精力去修改；

开发和维护该类的历史列表。记录每一次修改的作者、日期、修改的内容； 列举类的各种稳定状态。说明调用成员函数使类的状态产生的变迁； 对主要的算法必须加以解释说明，主要的流程必须给出引导性的说明。

标准格式：

/** * 描述类的功能、用途、现存 BUG，以及其它别人可能感兴趣的介绍。 * @author XXX * @version 最后修改日期 * @see需要参见的其它类 * @since从产品的那一个版本，此类被添加进来。（可选） * @deprecated 该类从产品的那一个版本后，已经被其它类替换。（可选） */ 5 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

如果对已经版本话的类进行了修改，需要按照如下格式为每一次修改附加修改历史记录： // 修改人 + 修改日期 // 修改说明

范例：

/** * MessageDispatcher 的主要功能是将消息源传来的各种消息，分发给相应的消息 * 处理器进行处理。 * 作者：张三 * @version 2000/04/20 * @see UFMessage, Event * @deprecated 从 2.0 版之后该类的功能被 EventDealer 取代，但为了保持向下兼容性，此类仍然被保留 */ // 李四 2000/05/21 // 添加了对帮助信息的处理函数 sendToHelpManager(UFMessage msg)。 // 王小二 2000/06/02 4.3 接口的注释

  

接口的注释风格基本与类的注释风格相同；

在别人使用接口之前，必须了解接口所包含的概念。检验一个接口是否应该定义的简单方法是：你是否能够容易的描述接口的用途；

接口如何应当和不应当被使用。开发者需要知道该接口如何被使用，也希望知道该接口不能被怎样使用。

4.4 函数的注释

     

函数头注释必须包括：函数执行了什么功能，为什么要这样处理；函数处理过程中对对象的哪些属性可能进行更改；函数执行前后，对象的状态； 比较、循环等控制结构必须加注释；（III）

在代码的功能并非一目了然的情况下，应当说明为什么要这样做； 局部变量必须加注释；（III） 复杂难写的代码必须加注释；

如果一系列代码的前后执行顺序有要求，必须注释说明。

函数头注释标准：

/** * 描述函数的功能、用途、对属性的更改，以及函数执行前后对象的状态。 * @param 参数说明 * @return 返回值 * @exception 异常描述 * @see 需要参见的其它内容 * @since 从类的那一个版本，此方法被添加进来。（可选）

6 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

* @deprecated 该方法从类的那一个版本后，已经被其它方法替换。（可选） */ 范例： /** * 将消息转发给帮助管理器，显示对应的帮助内容。 * @param msg ierp.sm.core.eo.UFMessage 消息的内容 * @return ierp.lang.boolean 帮助管理器是否正确接收到消息。 * @exception java.lang.NullPointException 如果消息为 NULL 抛出此异常。 * @see ierp.sm.core.eo.UFMessage * @since 从 2.0 版该方法被添加。 */

4.5 类属性的注释

   

描述域的用途。使别人知道如何去使用它；

注释对变量的固定。例如 dayOfMonth 域就应该注明它的值在 1-31 之间。通过注释对域的，帮助你定义重要的事物规则，也使别人更加容易理解你的代码；

对于有着复杂事物规则的域，可以加入范例来说明。有时候一个简单的小例子，抵的上千言万语；

必须理清，并且清楚的注明并发问题。并发错误是很难在调试和维护阶段发现和排除的；

4.6 局部变量的注释

 

每行只声明一个局部变量，并且在行末加入注释；

注释的参考内容为说明该变量被什么、在那里、为什么使用；

5 日志处理规范

     

统一使用Log4J记录日志

必须使用含义明确的完整语句，禁用输出“1111”,“ababa”等测试或记录 推荐对关键函数处理进行记录（II） 推荐记录业务流程信息(III)

因为System.out.println()，e.printStackTrace()仅把信息显示在控制台，因此不允许使用，必须使用logger打印并记录信息。

在所有异常被捕获且没有重新抛出的地方必须使用logger.error()记录日志。

6 异常处理规范



重新抛出的异常必须保留原来的异常，即throw new NewException(\"message\而不能写成throw new NewException(\"message\")。

7 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

 

在所有异常被捕获且没有重新抛出的地方必须使用logger.error()记录日志。 如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。

7 优化性能方面的建议

    

若没有足够理由，不要把实例或类变量声明为公有，尽可能的私有化。

除非程序的框架需要，否则绝对不要因为性能的原因将类、方法定义为 final 的。 对于较长字符串的应用，要尽量使用 StringBuffer 对象，而不是直接使用 String 对象。 尽量使用 interfaces 来替代 abstract 类。

exit() 方法只允许出现在 main 中，其他的地方不应该调用。

8 附录

8.1 匈牙利命名法前缀对应表

基本变量 变量类型 byte, short, int, long Float Double Char Boolean array 常用工具类 变量类型 String Vector Hash StringBuffer Object 前缀 n f d c b ary 范例 nCount fTotal dSum cTemp bEndOfLine aryEmployees 前缀 str vec hash sb obj 范例 strName vecPackage hashContainer sbSource objData

常用控件

控件类型 Button TextField TextArea CheckBox RadioButton List ComboBox

前缀 btn tf ta ckb rb list cbb 范例 btnOK tfName taNote ckbShowAll rbSex listDepartment cbbWorkCenter 8 / 9

北京车讯互联息服务有限公司 wwww.chexun.com

Lable Table Tree ProgressBar Panel ScrollPane TabbedPane Dialog Frame Menu lb tb tr pb pnl scp tbp dlg frm mn lbAddress tbItems trAccount pbMRP pnlVoucher scpPicture tbpMain dlgTip frmDesktop mnHelp

对于未定义标准前缀的类可以按照以下原则使用前缀：

1．由一个单词构成类名，可以将这个类名全部小写（或者先缩写），作为前缀，在后面再加上表明用途含

义的说明性修饰。如： Employee employeeRetired Mail mailUnread

2．由多个单词构成的类名，可以取每个单词的首字母组成缩写组合（根据情况可以添加若干体现单词发

音的字母），作为前缀。注意不要与标准前缀重复。 WorkCenter wcAvailable

DefautMessageEvent dfmeReceived

8.2 常用动词表

汉语含义 做某事 设置 取得 审核 增加 修改 删除 更新 查询 更新 返回、回复 接收 英文单词或缩写 do set get check add modify delete,remove update,refresh query, search, find change return receiver Chg Rtn Recv 范例 doQuery setName getName checkVoucher addEmployee modifyContent deleteWorkCenter

9 / 9