java 编码规范

ver 2009
目录 
一、 前言......................................................................................................................................................... 3
1. 背景 ................................................................................................................................................... 3
2. 编码规范级别定义............................................................................................................................. 3
3. 规范实施建议 .................................................................................................................................... 3
4. 定义和约定........................................................................................................................................ 3
5. 参考资料............................................................................................................................................ 4
二、 格式规范 ................................................................................................................................................. 4
1. 缩进 ................................................................................................................................................... 4
2. 行长度 ............................................................................................................................................... 4
3. 声明 ................................................................................................................................................... 4
a) 声明变量、常量 ................................................................................................................................ 4
b) 声明类 ............................................................................................................................................... 4
4. 语句 ................................................................................................................................................... 5
三、 命名规范 ................................................................................................................................................. 6
1. 通用规则............................................................................................................................................ 6
2. 附加说明............................................................................................................................................ 6
四、 组织规范 ................................................................................................................................................. 7
1. web工程目录规范 ............................................................................................................................ 7
2. 引入包规范........................................................................................................................................ 7
五、 注释规范 ................................................................................................................................................. 7
1. 通用注释规则 .................................................................................................................................... 7
a) 说明 ................................................................................................................................................... 7
b) javadoc注释标签语法定义说明 ...................................................................................................... 8
2. 类的注释............................................................................................................................................ 8
3. 方法的注释........................................................................................................................................ 9
4. 失效代码块的注释........................................................................................................................... 10
5. 分支语句的注释 .............................................................................................................................. 10
6. 变量、常量的注释........................................................................................................................... 11
六、 异常处理规范........................................................................................................................................ 11
七、 补充规范 ............................................................................................................................................... 11
一、前言

1. 背景 

在项目开发维护中，编码规范作为开发规范的一个组成部分，是十分重要和必须的，它不仅仅是为了
提高开发效率，也有利于降低后期维护开发的成本。编码规范的根本目的就是要让不仅代码可以一目了然，
也可以很容易的理解开发人员所编写的代码程的用途和意义。由此，用来减少项目中因为开发维护人员的
更替或由于长时间不维护造成的记忆模糊或混乱等情况带来的对代码所实现的真正功能的理解困难和歧
义。另外也提高了代码复查效率和效果。

2. 编码规范级别定义 

根据实际情况分为 2 类等级的规范：
9 必要规范 （默认）：对于新建或优化改造系统，开发维护人员必须严格遵守和保持。对于历史系统和
小范围调整的系统（2009 年前上线的系统），开发维护人员可以根据实际情况进行实施。
9 推荐规范（该条目标记为 【推荐】）：推荐规范即非强制规范，只是推荐和鼓励开发维护人员实施的编
码规范

3. 规范实施建议 

9 不是为了规范而规范，以提高软件开发质量和效率为目标，辅以 IDE 等开发工具为保障，逐步改进编

码规范化水平
9 对于格式规范、注释规范等部分规范的要求，可以通过使用 eclipse 自带的 Format 方法（快捷键：
Ctrl+Shift+F）进行自动格式化，可以提高开发效率又符合编码规范。
9 编码规范文档本身需要定期不断的修正和完善，以符合实际开发规范的要求。

4. 定义和约定 

9 【待讨论】
表示编码规范讨论时必须提出的待讨论内容
9 【推荐】
用该标签标示的条目表示是推荐规范
9 Pascal 标记法
 第 1 个字符大写，其后每个单词的第 1 个字母大写
9 camel 标记法
第 1 个字符小写，其后每个单词的第 1 个字母大写

5. 参考资料 

《Code Conventions for the Java Programming Language》

《The Elements of Java Style》

二、格式规范

1. 缩进 

使用 Tab 键缩进；
不允许使用空格键进行缩进。

2. 行长度 

每行 120 字符
注： 使用 eclipse 自带的 Format 方法（快捷键：Ctrl+Shift+F）时，需要配置“Maximum line width”
设置长度为 120

3. 声明 

a) 声明变量、常量 

一行只声明一个变量或常量；
在代码块的开始处声明变量，不要在首次用到该变量时才声明【推荐】

b) 声明类 

左大括号"{"位于声明语句同行的末尾，右大括号"}"另起一行；
 方法与方法之间以空行分隔

4. 语句 

可以使用 eclipse 自带的 Format 方法（快捷键：Ctrl+Shift+F）时 使用 eclipse 默认的“Control

Statements ”格式化方法进行
注：if 语句总是用"{"和"}"括起来

示例
class Example {
void bar() {
do {
} while (true);
try {
} catch (Exception e) {
} finally {
}
}

void foo2() {
if (true) {
return;
}
if (true) {
return;
} else if (false) {
return;
} else {
return;
}
}
}
三、命名规范

1. 通用规则 

标识符类型 命名规则 示例
包(Packages) 包名命名全部小写字母； cn.sh.sstic.mwbas
源代码使用 cn.sh.sstic 开头的包名； test.cn.sh.sstic.mwbas
测试代码使用 test.cn.sh.sstic 开头的包名
使用单个单词【推荐】
类(Classes) 类名命名采用 Pascal 标记法； class
类名是一个名词【推荐】 SaveProjectGroupActio
n
接口(Interfaces) 接口类名以大写“I”开头，命名采用 Pascal 标记法。 interface
IProjGroupService
方法(Methods) 方法名命名采用 camel 标记法； run();
方法名是一个动词【推荐】
变量(Variables) 变量名命名采用 camel 标记法； String[] projects
变量中代表多个值时以-s 等复数结尾； char c;
包含 Struts 中的 config.xml 文件的 path 和 name 命 int i;
名； float myWidth;
尽量避免单个字符的变量名，除非是一次性的临时变
量。临时变量通常被取名为 i，j，k，m 和 n，它们一
般用于整型；c，d，e，它们一般用于字符型； 【推荐】
变量名不应以下划线或美元符号开头【推荐】

常量(Constants) 常量命名全部大写，单词间用下划线隔开； public static final String

常量必须是静态、final 类型 INVITATION_TYPE_GENER
AL= "general";
JSP 文件(*.jsp) JSP 页面命名采用 camel 标记法； findExpertCheckState.js
包括 css 和 JavaScript 文件命名同 jsp 文件 p

2. 附加说明 

1、 从命名中可以直观看懂其定义和用途，否则必须增加注释说明；
2、 在同一系统内命名必须保持统一；避免出现类似示例中的情况；
示例：项目组 id 变量定义：pgid、projectgroupId、idprojectgroup、idProjGroup
3、 特殊约定名词可以直接使用缩写 kxx 或 rws 等，但必须在设计文档中准确说明；
4、 避免名字过长、命名采用英文缩写，避免使用汉语拼音【推荐】
四、组织规范

1. web 工程目录规范 

builder path
src：source code files
etc：configuration files
test ：JUnit test files
Web-root 文件夹：web
需要登录或控制的 jsp 必须存放在 web/secure 下
script 存放 javascript 文件
style 存放 css 文件
images 存放 图片文件

2. 引入包规范 

不仅对于源代码，也包括了 jsp 页面中的 import；

不允许引入类中未使用的包；
引入包时不能直接引入“.*”，必须明确到引入的类名

五、注释规范

1. 通用注释规则 

a) 说明 

9 注释要精简并清晰容易理解；
9 保持注释与代码同步，如果做不到，则删除注释。
9 代码质量不好但能正常运行，或者还没有实现的代码用 //TODO:任务 ；
9 存在错误隐患的代码用 //FIXME:声明；
9 对于不建议使用的类或者方法，必须在他们的注释中增加 @deprecated
 b) javadoc 注释标签语法定义说明 

@author 对类的说明 标明开发该类模块的作者

@version 对类的说明 标明该类模块的版本
@see 对类、属性、方法的说明 参考转向，也就是相关主题
@param 对方法的说明 对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说
@deprecated 对类或方法的说明 该类或方法不建议使用

2. 类的注释 

目的：简单概述该类作用

范围：所有 java 类，可以不包括 javabean

书写规范：类的注释必须写在该类的声明语法之前。在注释中要描述该类的描述，创建者，创建日期，和
CVS 相关的最后 commit 时间、人和版本等信息。

类注释模板：可以通过 eclipse 配置（Code Templates 中的 Code 的 New Java files）

${filecomment}
${package_declaration}

/**
* Title: ${project_name}<br>
* Description: <br>
* Copyright: Copyright (c) ${year} <br>
* Create DateTime: ${date} ${time} <br>
* CVS last modify person: $Author$ <br>
* CVS last modify DateTime: $Date$ 时间需+8 小时 <br>
* CVS last version: $Revision$ <br>
* @author 李伟诚
*/
${typecomment}
${type_declaration}

类注释示例：
package cn.sh.sstic.projectmanagement.projectfeasibleschemaeval;

/**
* Title: mwbas2008<br>
* Description: 可行性方案套数数组定义类<br>
* Create DateTime: Oct 6, 2008 4:41:03 PM <br>
* CVS last modify person: $Author: lwc $ <br>
* CVS last modify DateTime: $Date: 2008/09/18 02:33:42 $ 时间需+8小时<br>
* CVS last version: $Revision: 1.22 $ <br>
*
* @author 李伟诚
*/
public class FormUtil {

3. 方法的注释   

目的：简要概述该方法的功能，包括其参数、返回值意义的注释
注：如果参数的命名已非常清楚的情况下，可以不写注释

范围：java 类中的各种方法
注：接口的实现方法的注释应写在接口中而不是实现代码中；
对自动生成的 get/set 方法不需要添加注释；
如果方法允许 null 作为参数，或者允许返回值为 null，必须在 JavaDoc 中说明，如果没有说明，
方法的调用者不允许使用 null 作为参数，并认为返回值是 null 安全的。

书写规范：方法注释必须写在方法定义之前。该注释包括：方法其功能的简单 描述，方法的参数、返回
值类型、返回值意义简单的描述。

模板：对于已定义好的接口的方法，可以直接输入 /**回车 eclipse 可自动生成注释模板

示例：
/**
* 演示方法注释
* @param args
* @return
* 返回 null 表示没有找到
* @throws Exception
*/
private String[] demoFunction(String args) throws Exception{
return null;
}
4. 失效代码块的注释 

目的：对一块暂时不启用的代码进行注释。
注：这里并不是指垃圾、无用的代码，只是暂时不启用或暂时不明确的代码

书写规范：失效代码块采用块注释方法行注释方法进行标注。
注：采用注释块在 使用 eclipse 自带的 Format 方法（快捷键：Ctrl+Shift+F）时需要配置，去掉选中
“Enable block commnet formatting”

示例：

// if (1==1) {
//
// } else {
//
// }

或者

/* if (1 == 1) {
// 如果1与1相等的时候
String code1;
} else {
// 如果1与1不相等的时候
String code2;
}*/

5. 分支语句的注释 

目的：简单描述该分支条件的意义

书写规范：在分支语句代码的下一行进行注释

示例：
if (1==1) {
//如果1与1相等的时候
code
} else {
//如果1与1不相等的时候
code
}
6. 变量、常量的注释 

目的：简单描述该变量、常量的意义。
书写规范：变量、常量注释必须写在变量、常量定义之前或同一行中，简单描述其代表的意义。
注：对自循环所用的变量（i,j,k,）可以不需要注释。
示例：
String commitFlag; //提交标志

六、异常处理规范
重新抛出的异常必须保留原来的异常，即 throw new NewException("message", e); 而不能写成
throw new NewException("message")，更不能不继续往上层抛出异常。
针对重要的可捕获的业务相关异常，需创建异常处理类，在方法中捕获到异常后，反馈到用户界面上，
提示用户【推荐】

七、补充规范

commit 到 cvs 上的代码中不允许出现 System.out.println()等临时用代码，如必须则使用 log4j 工具进

行代码编写；
明确的垃圾或无用代码必须删除