查了Java项目命名规范 sun 在线文档 帮助文档。
- 级别I: 默认登记要求所有项目中的所有成员遵守。
- 级别II: 建议所有项目中的所有成员遵守。
- 级别III: 鼓励各个项目根据实际情况执行。
使用Tab缩进,而不是空格键--将缩进2,4,8字符的选择权留给阅读者。
每行120字符--因为已是1024*768的年代。
if,for,while语句只有单句时,如果该句可能引起阅读混淆,需要用" {"和"}"括起来,否则可以省略。
//
错误,需要使用花括号{}括起来
if
(condition)
if
(condition) doSomething();
else
doSomething();
- 遇到缩写如XML时,仅首字母大写,即loadXmlDocument()而不是loadXMLDocument()
- Package名必须全部小写,尽量使用单个单词
- Interface名可以是一个名词或形容词(加上'able','ible', or 'er'后缀),如Runnable,Accessible。
为了基于接口编程,不采用首字母为I或加上IF后缀的命名方式,如IBookDao,BookDaoIF。 - 局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)
- 修饰符应该按照如下顺序排列:public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。
- 类与接口的声明顺序(可用Eclipse的source->sort members功能自动排列):
- 静态成员变量 / Static Fields
- 静态初始化块 / Static Initializers
- 成员变量 / Fields
- 初始化块 / Initializers
- 构造器 / Constructors
- 静态成员方法 / Static Methods
- 成员方法 / Methods
- 类型(内部类) / Types(Inner Classes)
同等的类型,按public, protected, private的顺序排列。
略。
由/*...*/界定,标准的C-Style的注释。专用于注释已失效的代码。
/*
* Comment out the code
* String s = "hello";
* System.out.println(s);
*/
由//界定,专用于注释代码细节,即使有多行注释也仍然使用//,以便与用/**/注释的失效代码分开
除了私有变量外,不推荐使用行末注释。
class
MyClass {
private
int
myField;
//
An end-line comment.
public
void
myMethod {
//
a very very long
//
comment.
if
(condition1) {
//
condition1 comment
...
}
else
{
//
elses condition comment
...
}
}
}
- 注释中的第一个句子要以(英文)句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。
- 为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法,尽量多的使用@see xxx.MyClass,@see xx.MyClass#find(String)。
- Class必须以@author 作者名声明作者,不需要声明@version与@date,由版本管理系统保留此信息。(II)
- 如果注释中有超过一个段落,用<p>分隔。(II)
- 示例代码以<pre></pre>包裹。(II)
- 标识(java keyword, class/method/field/argument名,Constants) 以<code></code>包裹。(II)
- 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。(II)
注释中的每一个单词都要有其不可缺少的意义,注释里不写"@param name -名字"这样的废话。
如果该注释是废话,连同标签删掉它,而不是自动生成一堆空的标签,如空的@param name,空的@return。
- 对于API函数如果存在契约,必须写明它的前置条件(precondition),后置条件(postcondition),及不变式(invariant)。(II)
- 对于调用复杂的API尽量提供代码示例。(II)
- 对于已知的Bug需要声明。(II)
如果方法允许Null作为参数,或者允许返回值为Null,必须在JavaDoc中说明。
如果没有说明,方法的调用者不允许使用Null作为参数,并认为返回值是Null Safe的。
/**
* 获取对象.
*
* @ return the object to found or null if not found.
*/
Object get(Integer id){
...
}
- 代码质量不好但能正常运行,或者还没有实现的代码用//TODO: 或 //XXX:声明
- 存在错误隐患的代码用//FIXME:声明
- 当面对不可知的调用者时,方法需要对输入参数进行校验,如不符合抛出IllegalArgumentException,建议使用Spring的Assert系列函数。
- 隐藏工具类的构造器,确保只有static方法和变量的类不能被构造
- 变量定义尽量基于接口而不是具体实现类,如Map map = new HashMap()
- 代码中不能使用System.out.println(),e.printStackTrace(),必须使用logger打印信息。
- 重新抛出的异常必须保留原来的异常,即throw new NewException("message",e); 而不能写成throw new NewException("message")。
- 在所有异常被捕获且没有重新抛出的地方必须写日志。
- 如果属于正常异常的空异常处理块必须注释说明原因,否则不允许空的catch块。
- 框架尽量捕获低级异常,并封装成高级异常重新抛出,隐藏低级异常的细节。(III)
- DAC度量值不要不大于7 ( III )
解释:DAC(Data Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一种代码度量。DAC度量值表示一个类中有实例化的其它类的个数。 - CFO度量值不要不大于20 ( III )
解释:CFO(Class Fan Out)类扇出是描述类之间的耦合度的一种代码度量。CFO度量值表示一个类依赖的其他类的个数。 - 方法(构造器)参数在7个以内 ( II )
太多的方法(构造器)参数影响代码可读性,还是不良设计的征兆。考虑用值对象代替这些参数,或者重新设计。 - 方法长度150行以内 ( II )
太长的方法影响代码可读性,还是一个方法承担了太多责任的征兆。建议拆分责任。 - CC 度量值不大于10(III )
解释:CC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量,可以用一个方法内if,while,do,for,catch,switch,case,?:语句与&&,||操作符的总个数来度量。 - NPath度量值不大于200 ( III )
解释:NPath度量值表示一个方法内可能的执行路径的条数。 - 布尔表达式中的布尔运算符(&&,||)的个数不超过3个(III)
- if语句的嵌套层数3层以内(II)
- 文件长度2000行以内(II)
太大的源程序文件影响代码可读性,还是一个类承担了太多责任的征兆,建议拆分责任到其他类上。 - 匿名内部类20行以内 ( II )
太长的匿名内部类影响代码可读性。建议:重构为命名的(普通)内部类。
- 重载方法必须使用@Override,可避免父类方法改变时导致重载函数失效。
- 不需要关心的warning报告用@SuppressWarnings("unused"),@SuppressWarnings("unchecked"),@SuppressWarnings("serial") 注释掉
Inellij IDEA的代码校验已经可以查出很多的代码质量问题。再配合使用Checkstyle,PMD,FindBugs三重检查,涵盖了大部分的代码GuideLine。
- Eclipse:在Windows->Preferences->Java-Compiler->Errors/Warnings中,按本文档的规则将一些原来Ignore的规则打开。
- IDEA:在Setting->Errors中设定规则,调用Analyzer->Inspece Code进行校验。
- CheckStyle:安装CheckStyle的Eclipse插件,在Windows->Preferences->CheckStyle导入springside团队预设在/tools/codereviewer/springside_check.xml的规则
- PMD:安装PMD的Eclipse插件,Windows->Preferences->PMD清除原来所有规则,导入springside团队预设在/tools/codereviewer/springside_pmd.xml的RuleSet。
- FindBugs:安装FindBugs的Eclipse插件,在项目属性->FindBugs中,取消下列警告MS/EI/EI2/ , SnVI/SE/WS/RS ,ST/NP/UwF/SS/UuF|UrF|SIC
5.参考资料Sun's Coding Conventions
- Sun MicroSystem;
- The Elements of Java Style
- 代码检测工具的规则: checkstyle,pmd ,findbugs
命名规则
这里规定并说明了设计,编写代码时的命名规则。所有开发人员必须无条件遵守,并按照这个命名规则来命名。如有不足,不合理请提出来,项目开始之前可以更正。※本文没有特别声明的英文字母,和阿拉伯数字全是半角。
1.基本设计工程
1.1.画面命名
项目代号[3位] + 模块代码[3位] + 页面数字[2位] 共 8位
项目代号[3位]:THP[TongshidaHomePage]
模块代码[3位]:A01[首页] B01[公司简介],B02[公司沿革],
页面数字[2位]:THPB0101[公司简介页面],
THPC0101[留言版显示页面],
THPC0102[留言版更新页面],
※数字要从01开始递增,无00页面。
1.2.数据库命名
数据库名:项目代号[3位] + "DB"(THPDB)
表命名:易懂的小写英文名名词,例如userif,department 字段名:
使用若干个易懂的小写英文名。例如userid,username,departid,
2.详细设计工程
2.1.程序名
1)Action程序命名:画面ID[8位] + Action名[若干位] + Action.java
(1)画面ID[8位]:同[1.1.画面命名]
(2)Action名[若干位]:开头字母大写。
共同命名:开头大写,后面小写 自由命名:
(3)Action程序最后必须添加[Action.java]来表示它是Action程序。
(4)最终取名例子:
例)THPB0101InitAction.java
[公司简介页面-初期处理Action]
THPB0101SearchAction.java
[公司简介页面-检索新闻处理Action]
2)FormBean程序命名:画面ID[8位] + Form名[若干位] + Form.java
(1)画面ID[8位]:同[1.1.画面命名]
(2)Form程序命名[若干位]:开头字母大写。 共同命名: 自由命名:
(3)FormBean程序最后必须添加[Form.java]来表示它是FormBean程序。
(4)最终取名例子:
例)
THPB0101MainForm.java
[公司简介页面-主要内容FormBean]
THPB0101NewsListForm.java
[公司简介页面-新闻检索结果集FormBean]
THPB0101NoticeListForm.java
[公司简介页面-公告检索结果集FormBean]
3.代码工程(PG工程)
3.1 .Java文件包的结构(目录结构)
1)包名必须全部是英文小写,下面是包的结构
/com
/tongshida
/common
/comp
/db
/comweb
/THPB0101
/action
/form
/THPC0101
2)[com.tongshida]: 表示这个包以下是,通事达公司所有或通事达公司开发,com是公司的意思
3)[com.tongshida.common]:这个包以下放置,可以和别的项目也就是将来开发时能重复使用的程序。比如共同函数等。
4)[com.tongshida.comweb]: 放置只能用于这次项目开发里的,和以后别的项目无法或很难重复使用的Java程序。比如具体业务逻辑。
5)[com.tongshida.comcom.comp]: 放置能在以后项目中可重复使用的共同函数。
6)[com.tongshida.comweb.画面ID]: 以画面为单位,分开放置本次开发项目的业务逻辑部分的Java程序。
7)[com.tongshida.comweb.画面ID.action]: 放置画面的动作实行对象,也就是Action对象(也就是Action的Java文件)。
8)[com.tongshida.comweb.画面ID.form]: 放置画面数据的FormBen对象(也就是ActionForm的Java文件)。
3.2.Import 的命名规则
1)Import 里头不许用[*],要把所有使用到的对象全都罗列出来。
2)和Import无关,但写SQL文当中select文时,也不允许写select *, 必须把要检索出来的字段名都写出来,1个字段或100个以上字段都得罗列字段名。例)select username,password,age from userif 不能写select * from userif
3.3 .对象名称
1)对象名(Class名)必须与文件名(java文件)一致.
例如,THPB0101InitAction.java 文件里的对象必须是
HPB0101InitAction.
3.4 .变量的命名规则
1)static final常量的命名:
(1)必须全部大写
(2)由多个英文单词组成时,要以下划线[_]分割
例如,DBSERVER_USERID,DBSERVER_PASS
2)起普通的变量名称:
(1)由多个英文单词组成时,开头单词要小写,后面的单词开头都大写。
例)String userName = "Tom"
(2)for循环中使用的变量,原则上适用小写 i,j,k。
例)for (int i = 0; i < sales.length; i++)
3)对象变量的名称:
(1)原则上去掉画面ID后,头字母小写使用。
例)THPB0101MainForm mainForm = new THPB0101MainForm();
(2)尽量能在变量名中显示变量的对象名称。
例)ResultSet newsListRs = new ResultSet();
3.5 .方法的命名规则
1)开头英文字母要小写,每个单词开头要大写
2)开头的英文单词要以动词开始,后面一般跟着名词英文单词
例)setName(),getPass()
3)取名时一般要遵守一下动词单词的对称性
add<=>remove,insert<=>delete,get<=>set,start<=>stop,begin<=>end,
send<=>receive,first<=>last,put<=>get,up<=>down,show<=>hide,
source<=>target,open<=>close,等等...以外也有很多
3.6 .JSP画面的目录结构。
1)JSP目录结构。
/项目名
index.jsp
/JSP
/THPA01
THPA0101.jsp
THPA0102.jsp
/THPA02
THPA0201.jsp
THPA0202.jsp
3.7.不好的无意义的命名。
1)光用以下单词的命名。
Info 修正后 userInfo,guestInfo,studentInfo
Data 修正后 newsDataRS(RS是 ResultSet)
还有对于项目名称的命名好像不是很严格。