目录
.概述
1.1背景
1.2目的
1.3适用范围
1.4名词解释
1.5文档说明
2.文件规范
2.1文件编码
2.2文件命名
2.3配置文件的选择
3.排版风格
3.1总原则
3.2列宽/换行
3.3声明
3.4缩进
3.5空行
3.6空格
3.7对齐
3.8小括号
3.9花括号
3.10代码长度
4.命名规范
4.1命名总则
4.2命名空间
4.3类与接口
4.4方法
4.5参数
4.6属性
4.7常量
4.8变量
4.9集合
4.10异常
4.11控件
4.12关键字
4.13命名示例
5.语句规范
5.1语句总则
5.2循环语句
5.3Switch-case
6.注释规范
6.1注释总则
6.2文档注释
6.3屏蔽代码
6.4类注释
6.5函数注释
6.6代码注释
6.7变量注释
6.8修改别人的代码
6.9单行注释
6.10其他注释
7.编码格式
7.1基本原则
7.2类编码格式
7.3变量
7.4方法
7.5书写规范
8.其他
8.1工程规范
8.2目录结构
8.3JavaBean
8.4单元测试规范
8.5技巧经验
编码规范对于程序员而言尤为重要,有以下几个原因:
全公司所有JAVA项目及程序
项目中如下文件均采用UTF-8编码格式:
.java .jsp .js .html .htm .shtml .vm .ftl .xml .txt .json .css |
文件类型 |
命名方式 |
示例 |
.java |
Pascal命名法 |
CookieUtil.java |
.jsp .js .html .htm |
中划线命名法 |
view-bundle.ftl |
Window->Preferences>Java>Code Style>Formatter>右侧窗口Edit按钮>弹出窗口中Line Wrapping选项卡->Maximum line width
2. 在任何情况下, 超长的语句应该在一个逗号后或一个操作符前折行。
例1,逗号后换行:
public static JSONObject wrap(Object data, boolean successs, long results, |
例2,操作符换前换行:
String finalMethodName = "init" + firstChar |
例3,属性操作符前换行:
char firstChar = Character.toTitleCase(invokeMethod |
3. 一条语句折行后, 应该比原来的语句再缩进4个空格,以便于阅读。
每行只能声明一个变量,如:
// indentation level
|
禁止:
int level, size; |
每个缩进单位为4个英文空格,不要在代码中使用Tab字符,可以在开发工具中将tab键设置为4个字符,eclipse设置缩进方法如下:
WindowPreferencesjavacodestyleFormatter,然后点击edit按钮,在Indentation页签中的General Settings选项集里,将Tab policy由Tabs only改为Spaces only,并保持Indetation size和tab size为4, 最后在最上方的Profile name里任意输入字符,保存当前页设置即可 |
按层级缩进,缩进层级不能超过5层,否则需要拆分函数
public void methodName(int age) { |
使用一个空行情况:
两个空行使用情况:
需要增加空格的地方有:
情形 |
示例 |
在大多数运算符之前和之后 |
if (a + b > c) |
"(" 的前面 |
例如:if ((a>b) && (c>d)) 不要写成 if((a>b)&&(c>d)) |
|, &, ||, && 前后 |
if (a>b && c>d) |
"=" 前后 |
a = 100; |
三元操作符 ? : 的前后 |
maxValue = a>b ? a : b; |
函数调用的各个参数之间 |
getData(param1, param2, param3); |
比较符前后 |
a > b //不强制 |
case 的后面 |
case "none" |
语句表达式之间 |
for (expr1; expr2; expr3) |
1. 当不清楚是否应该加小括号时请添加小括号,否则很难看明白其含义。
推荐:
if (((a - b) << 2) > ((c - d) >> 4)) { |
不推荐:
if (a - b << 2 > c - d >> 4) { |
2. 尽量不要在返回语句中使用()。
{} 中的语句应该单独作为一行,左括号"{"当紧跟其语句后(即:在它后面换行),右括号"}"永远单独作为一行且与其匹配行对齐,并尽量在其后说明其匹配的功能模块。如:
public String getFirstNode(List |
类的名字必须由大写字母开头而其他字母都小写的单词组成,对于所有标识符,其中包含的所有单词都应紧靠在一起,而且大写中间单词的首字母,一般使用名词命名。
public abstract class AbstractWebService { |
接口的第一个字符用"I"开头,Service结尾,实现类的命名统一以"ServiceImpl"结尾。
public interface IUserInfoQryService{
|
getName() |
6. 获取单条记录的:findByXXX()
7. 获取List集合的:listByXXX()
8. 分页查询的:pageXXX()
使用有意义的参数命名,如果可能的话,使用和要赋值的字段一样的名字,并用this区分:
public void setSize(int size) { |
方法参数建议顺序:(被操作者,操作内容,操作标志,其他……) 例:
/** |
以下规则概述属性的命名指南:
用名词加集合名称的方式来命名,第一个单词首字母小写,如:
List |
数组应该总是用下面的方式来命名:
应采用完整的英文描述符命名组件,遵循匈牙利命名法则。如:btnOK,lblName。
不要使用语言本身已经占用的关键字或保留字命名。
abstract default if private this |
操作项 |
命名约定 |
示例 |
参数 |
使用传递值/对象的完整的英文描符。 |
userID |
字段/属性 |
字段采用完整的英文描述,首字母小写,任何中间单词的首字母大写。 |
firstName |
布尔型方法 |
用is或has做前缀 |
isEnough(), hasMoney() |
类 |
采用完整的英文描述符,所有单词首字母大写 |
Customer, CustomerCounterTest |
源文件 |
命名同类的定义 |
Customer.java |
部件/组件 |
使用完整的英文描述来说明组件的用途,将组件类型使用匈牙利命名法则作其前缀。 |
btnOK, cboTypeList |
构造函数 |
默认的构造函数同类名 |
Customer() |
异常类名 |
由表示该异常类型等的单词和Exception组成 |
SQLException, ServiceException |
异常实例名 |
通常采用字母 e 、ex表示异常。 |
e, ex, SQLEx |
常量 |
全部采用大写字母,单词之间用下划线分隔。 |
DEFAULT_NAME |
获取成员函数 |
被访问字段名的前面加上前缀 get。 |
getUserName() |
接口/实现类 |
使用I前缀/接口实现类命名同接口去掉I的部分,并以Impl做后缀。 |
IUserService/UserServiceImpl |
局部变量 |
采用完整的英文描述符,第一个字母小写 |
totalMoney |
循环计数器 |
通常采用字母 i,j,k |
i, j, k |
包 |
采用完整的英文描述符,所有单词都小写,所有包属于com.glodon |
com.glodon.gcp.buyer, |
方法 |
采用完整的英文描述说明方法功能 第一个单词尽可能采用一个生动的动词,除第一个单词外,每个单词第一个字母大写。 |
openFile() |
对于流操作代码的异常捕获有finally操作以关闭流对象,比如:
/** |
尽量不用空语句,特殊情况用到空语句,写好注释,告诉读者这不是bug
for (initialization; condition; update){ |
while (condition){ |
所有的非空 case 语句必须用 break; 语句结束。例:
switch (score) { |
Javadoc注释可以产生代码的文档。为了可读性,可以有缩进和格式控制。文档注释常采用一些标签进行文档的特定用途描述,用于帮助Javadoc产生文档,常用的有:
标签 |
应用对象 |
目的 |
@author name |
类/接口 |
描述代码的作者,每个作者对应一个这样的标签 |
@deprecated |
类 |
说明该段API已经被废除 |
@exception name description |
成员方法 |
描述方法抛出的异常 |
@param name description |
成员方法 |
描述成员方法中的参数用途和意义,一个参数对应一个这样的标签 |
@return description |
成员方法 |
描述成员方法的返回值的意义 |
@since |
类/接口 |
描述该段API开始的时间 |
@see ClassName |
类/接口 |
用于引用特定的类描述,一般ClassName用包括包名的全名 |
@see ClassName#memberfunction |
类/接口 |
用于引用特定的类的成员方法的描述,一般ClassName用包括包名的全名 |
@version text |
类/接口 |
版本 |
@inheritDoc |
类/接口 |
继承的文档 |
对于临时废弃或为了调试程序而临时屏蔽的代码段,可以注释掉。如:
/** |
在类、接口定义之前当对其进行注释,一般比较详细,其内容至少要包含:功能说明、@author作者、@version版本, @date创建日期、 (see参照,)since开始版本等几个方面。
为了使形成的文档可读性好,注释中经常带有缩进和格式控制。类描述放在类的类定义的紧前面,不能有任何的空行。
以jdk的Number类为例:
/** |
依据标准JavaDoc规范对方法进行注释,以明确该方法功能、作用、各参数含义以及返回值等。复杂的算法用/**/在方法内注解出。
注释可以很详细,为了可读性强也可包含格式控制,方法注释一般包括:
/** e.printStackTrace(); |
例:
//用户名 |
算法设置
算法描述指在实现级别的描述注释,如在方法内的注释,这样使得程序更加易懂,方便程序算法的修改和BUG的修复。一般采用块/行注释,对于简短的描述采用行注释,不要用文档注释。注释的主要内容包括:
块注释: /* */
可以用多行,一般用来对程序块、算法实现、类的实现进行说明。为了可读性,可以有缩进和格式控制。一般在行注释不能满足注释需要的时候采用。一般用来作为文件头、复杂算法的说明,方法体内的复杂过程说明等
1. 成员变量、类静态变量采用文档注释,对成员变量的注释通常包括:
/** XXXXXX */ |
2. 局部变量,如算法相关的变量采用块或行注释
String username = "xyz"; //用户姓名 |
3. 参数变量注释一般用文档注释,并且用@param来说明为参数,一般包括:
增、删、改
原则上尽量不要修改别人的代码,而是提出需求,由相应的代码责任人负责修改。
如果由于客观条件导致必须修改别人的代码,则尽量征得责任人的同意,同时在修改的地方添加修改注释,格式如下:
用"+"表示增加代码
//yangym20120601 +2 |
用"-"表示删除代码
/** yangym20120601 - |
用"*"表示修改代码
//listCount = i; |
添加方法
用标准javadoc对方法进行注释,并注明作者和日期
添加字段
需要添加作者信息注释。如:
String userName = null; //yangym20120601 |
//一次只能注释一行,一般用来简短的描述某一个局部变量,程序块的作用。
禁止后台业务层代码使用如下代码,要输出日志,同时进行异常包装抛出。
try{ |
import顺序
2. 每一类import后面加一个换行。例如:
import java.io.*; |
3. 类的结构组织,一般按照如下的顺序:
这种顺序是推荐的,在实际开发中可以按照一定的尺度修改,原则是程序更易读。如对方法的排序按照重要性,或按照字母顺序排列或按照方法之间的关系排列。
4. 每个方法(包括构造与finalize)都是一个段。多个变量声明按照逻辑共同组成一个段,段与段之间以空行分隔。
5. 类声明时,要指出其访问控制,一般为没有修饰符,public,和private。
6. 编写通用性的类时,请遵守标准形式。包括定义equals()、hasCode()、toString()、Clone(实现Cloneable接口),并实现Comparable和Serialiable接口
7. 对于设计期间不需要继承的类,尽量使用final
变量的声明要放在程序块的开始位置,如:
void myMethod() { |
一种例外情况是在for语句中,定义声明不仅不占一行,还在表达式内部,完全采用Eclips生成,如:
for(int i = 0; i<100; i++)
4. 数组的申明采用 <数据类型[] + 变量名>方式如:
5. char[] buffer; 而不是: char buffer[];
推荐:
public void myFun(){ |
禁止:
public void myFun(){ } |
在字符串变量在与字符串常数作比较时,字符串常数放在比较表达式的前面如:
String str="bbb"; |
Return语句中不要用小括号,除非使表达更清晰,如:
return (list.size() > 0 ? list.get(0) : null); |
目录 |
说明 |
||
ProjectName |
项目名称 |
||
/build |
构建目录 |
||
/classes |
类构建目录 |
||
/src |
Java源文件目录,各种配置文件存放根目录 |
||
/web |
Web目录 |
||
/common |
公用跳转页面,如404.jsp |
||
/css |
css文件目录 |
||
/decorators |
公用vm装饰页面 |
||
/gcp |
项目页面存放目录 |
||
/images |
图片存放目录 |
||
/script |
Js脚本存放目录 |
||
/WEB-INF |
Web配置文件,lib库 |