MyException - 我的异常网
当前位置:我的异常网» 移动开发 » Java编码轨范

Java编码轨范

www.MyException.Cn  网友分享于:2015-08-26  浏览:4次
Java编码规范
外部参考

英文:http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
译文:http://www.huihoo.org/code/java_code_conventions.html
前言

结构规定

结构概览
文件头声明
Package行
Import块
类声明
静态域
静态初始化块
public静态方法
实例域
实例初始化块
构造子
实例方法
非public静态方法
具名内部类
文件头声明
文件头注释:标明版权信息和SVN版本替换标签(可选)两部分内容,参见下图:

在源码提交SVN服务器后,SVN版本替换标签信息将自动替换为文件名称、版本号、提交版本服务器时间、提交用户名等内容,如下图所示:

使用此特性前,需要作一些设置,请参考: [[http://johnbokma.com/mexit/2008/09/30/subversion-svn-keywords-property.html ]]
Package行
Package声明紧跟在文件头声明内容之后、Import块之前,与其后内容留一空行,如下图所示:

可使用Eclipse格式化自动完成。
Import块
Import块在Package行之后、类声明之前,与前后内容之间各留一空行
静态导入(import static)在前,类导入在后
静态导入内容必须精确到变量或方法、导入类必须精确到具体的类
不同导入部分之间留一空行
如下图所示:

可使用Eclipse 快捷方式 ctrl + shirt + o自动完成。
类声明
包括类Java Doc注释和类声明行两部分,注释在前,声明在后。
类注释在Import块之后,与其之间有一空行
类注释需填写类摘要说明、@author等必选信息,根据需要填写@version, @since等信息
作为API提供的类,应在注释中简单说明如何使用,以及其它有助于快速、正确使用它的有关信息
类注释后紧跟类声明,其间无空行
如下图所示:

静态域&静态初始化块
越接近Java底层的越在前,越远离Java底层的越在后(serialVersionUID);
final域在前,非final域变量在后; public 在前,private在后;
域的初始化块紧接在域声明后,分开使用初始化块,不合成一起
综合初始化块,在所有域和静态初始化块后

public静态方法
public静态方法在实例域和构造子之前
main方法在所有静态方法之前
main方法要对输入参数格式做注释说明
实例域&实例初始化块
实例域应定义为private或protected,谨慎使用public
实例域应提供简单的/** */单行注释,标明其中文名称或职责功能,抑或通过//进行单行注释
实例域与实例域之间空一行

构造子
构造子在实例成员后,实例方法前;
根据Java语言规范,当类没有声明任何构造子时,Java认为其默认具有一个无参构造子;
当类明确声明了构造子,Java不再为类默认添加任何构造子;
有多个构造子时,参数少的在前,多的在后。
构造子的注释应该注重说明意图以及参数对对象的影响;
构造子的个数应该控制在有限个数内,否则应该使用Builder模式、静态工厂方法模式等替代方案(请参见<Effective Java>);
实例方法顺序
一般原则:
public方法 (注1)
protected方法 (注1)
package方法 (注1)
private方法
getter/setter方法
对一组功能类似的方法,short-cut的方法在前,复杂的方法在后
注1:包括abstract的实现、声明,对父类方法的override,只被构造函数调用的init方法
以上系一般原则。但亦可例外,前提是需要有充分的理由,并通过行注释进行简单说明(否则他人可能进行调整),无法说明充分理由的,应保持队列。
实例方法的声明
对abstract方法实现的,重写父类方法的,必须声明@Override;
对有相同参数个数的重载方法(overloaded)或称多态方法的,应该非常谨慎,改个名字最好;
对public、protected一定要写Java Doc注释,而且是有效的。




非public静态方法
原则上:所有非public静态方法应该在所有实例方法之后,具名内部类前。这类静态方法往往是一些函数性、工具性的方法。
特例:有些非public静态方法,是为一组功能相似或紧密的方法使用的,如果放在这些静态或实例方法后面更有助于代码阅读,应贯彻此特例。这类同于short-cut请参考 String.java的indexOf和lastIndexOf两个静态方法的位置。
其他规定

代码字符规定
源代码使用UTF-8进行编码,创建Java工程时应进行确认或调整。请把Eclpse的默认环境设置为UTF-8 Eclipse->General->Workspace->Text file encoding->Other UTF-8
源代码换行符,明确调整为Unix方式
我们的开发人员普遍使用Window和Unix操作系统开发,为统一起见而规此定。Eclipse->General->Workspace->New Text file line delimiter->Other Unix
代码长宽限制
Java源文件从文件头声明到结束总长度禁止超过1200行
Java方法代码长度尽量避免超过100行,禁止超过100行(不含方法头的Java Doc注释)
Java源文件宽度禁止超过100英文字符的宽度(请通过Eclipse等IDE进行设置控制,请注意中文字符的宽度大于英文字符,所以应使用Eclipse控制注释的宽度在80个以内)
每个Java代码行(不管是否折行了),在调用方可调整的情况下,禁止超过100个字符
违反以上规定,不仅仅妨碍了代码可读性的提高,往往也意味中代码在设计、开发上有相当的改进空间。应寻找时间改善,提升代码设计质量、可维护性。
对于第4点,往往是在方法调用中,过多地使用表达式作为方法的参数导致的。过多的使用会导致阅读困难。同时也可能是API提供方需要传入过多的参数造成的,虽然作为客户程序无法改变,但是也应该进行一定的提醒,建议提供进行恰当修改。
代码折行策略
在分隔符号后折行
逗号(,) 分号(;) 赋值号(=)

Eclipse格式化可以自动调整,使符合此规范
在运算符号前折行
算术符号(+, -, *),关系运算符(&&, ||), ...

考虑使用行注释符//
IDE的折行策略大部分是可行的,但是也有一些折行,IDE工具处理得很糟糕。
通过行注释符可以强制改变IDE自动折行策略,使按照我们定义的方式折行。可在 // 后,写 NL (=new line),以明确告知读者,这里用于折行。

代码缩进策略
使用4个空格作为块缩进,为良好支持各种编辑器,应避免使用跳格符号tab缩进,Eclipse格式化可以自动调整,使符合此规范。
Clean-up
一行文本行,不要有2个代码行:argv++; argc--; // AVOID!
对单独的if-else里面的语句,强制使用括号
覆盖或实现父类的方法必须标明注解:@Override
Annotation标注风格

注释规定
对public和protected的元素都必须写Java Doc注释:说明API意图/功能(第一行)、是否可用于多线程(默认不说明应该保证可用于多线程下)、是否是线程安全的(默认不说明应该保证线程安全) 、输入参数规格(@param)、输出规格(@return)、对象或参数处于某特定状态将抛什么异常(@throws),以及对使用该类或方法的前提条件以及后置条件进行说明(如有限制的话)
Java Doc注释不要过多陈述“代码的内部实现”,而应从使用这的角度进行陈述。
对public/protected元素而言,Java Doc说明甚至是最重要的资产。
对private方法,也应该简单说明一下其意图或功能,以便于后续维护。
对有格式要求的普通注释,可使用/*- */的形式进行块注释,如下:
  /*-
   * Here is a block comment with some very special
   * formatting that I want indent(1) to ignore.
   *
   *    one
   *        two
   *            three
   */
泛型使用规定
按照《Effective Java》建议,在新代码中应该使用泛型;
对List,Set, Map等集合类,我们强制使用;
对兼容旧代码的,实在没办法处理的,必须使用@SuppressWarnings("uncheck")处理,但禁止在Class级别使用,只能使用在方法或变量级别;
提交到版本库的代码不能出现warnnings警告
日志打印规定
对日志打印,请使用Log日志对象,不使用System.out.println()或System.err.println();或e.priintStackTrace() 日志对象写法如下:
private/protected Log logger = LogFactory.getLog(getClass());  或
private/protected static Log logger= LogFactory.getLog(Xxx.class);
避免新代码中写入这样的语句:
private/protected Log logger = LogFactory.getLog(“core”);
书写DEBUG日志前,必须进行logger.isDebuggable() 判断
logger.error(ex); 错;
logger.error(“”, ex); 对!
极特殊情况下,使用Sytem.out/err输出日志的,应在源代码中作出理由说明
分页参数统一
采用page + count的方式处理(包括命名):
page 表示页数,取值1、2、3...表示第1、2、3...页
count 表示每一页的数量
不采用offset、size等方式以及命名了
SQL规范
NO! SELECT * FROM table;
YES! SELECT id, name FROM table;
IDE自动化

Eclipse
[必 须]
请导入opi-java-formatter-x.y.xml以及opi-java-cleanup-x.y.xml两个文件
在把源代码提交到版本控制器前,必须保证源代码符合以下2个文件的定义:
Eclipse->Window->Preferences->Java->Code Style>Formatter->Import->->OK
获取地址: \\10.2.18.44\\xntech\\!ebook\\_开发规范\\Java源文件规范1.1\\opi-java-formatter-1.1.xml
使用Ctrl + Shirt + F执行格式化
Eclipse->Window->Preferences->Java->Code Style->Clean Up->Import->OK
获取地址:\\10.2.18.44\\xntech\\!ebook\\_开发规范\\Java源文件规范1.1\\opi-java-cleanup-1.1.xml
在所在的类->右键->Source->Clean Up 执行自动清理
Find-Bugs插件
[必 须]
请安装Find Bugs插件,http://findbugs.cs.umd.edu/eclipse/
提交代码前,必须通过通过Find Bugs测试通过没有警告。
Eclipse->右健工程名或Java源文件->Find Bugs->找到Find Bugs警告(在编辑器左边会出现一只小虫)
->鼠标移到小虫上,查看警告提示并进行修复->修复后可提交到版本库
Find Bugs并不能找出所有Bug,它只是自动化工作的一部分。

文章评论

程序员的一天:一寸光阴一寸金
程序员的一天:一寸光阴一寸金
Web开发者需具备的8个好习惯
Web开发者需具备的8个好习惯
老美怎么看待阿里赴美上市
老美怎么看待阿里赴美上市
程序猿的崛起——Growth Hacker
程序猿的崛起——Growth Hacker
要嫁就嫁程序猿—钱多话少死的早
要嫁就嫁程序猿—钱多话少死的早
科技史上最臭名昭著的13大罪犯
科技史上最臭名昭著的13大罪犯
10个帮程序员减压放松的网站
10个帮程序员减压放松的网站
一个程序员的时间管理
一个程序员的时间管理
程序员应该关注的一些事儿
程序员应该关注的一些事儿
十大编程算法助程序员走上高手之路
十大编程算法助程序员走上高手之路
那些争议最大的编程观点
那些争议最大的编程观点
程序员周末都喜欢做什么?
程序员周末都喜欢做什么?
亲爱的项目经理,我恨你
亲爱的项目经理,我恨你
做程序猿的老婆应该注意的一些事情
做程序猿的老婆应该注意的一些事情
2013年中国软件开发者薪资调查报告
2013年中国软件开发者薪资调查报告
聊聊HTTPS和SSL/TLS协议
聊聊HTTPS和SSL/TLS协议
如何区分一个程序员是“老手“还是“新手“?
如何区分一个程序员是“老手“还是“新手“?
“懒”出效率是程序员的美德
“懒”出效率是程序员的美德
Web开发人员为什么越来越懒了?
Web开发人员为什么越来越懒了?
编程语言是女人
编程语言是女人
为啥Android手机总会越用越慢?
为啥Android手机总会越用越慢?
我是如何打败拖延症的
我是如何打败拖延症的
我的丈夫是个程序员
我的丈夫是个程序员
为什么程序员都是夜猫子
为什么程序员都是夜猫子
“肮脏的”IT工作排行榜
“肮脏的”IT工作排行榜
60个开发者不容错过的免费资源库
60个开发者不容错过的免费资源库
Java程序员必看电影
Java程序员必看电影
Java 与 .NET 的平台发展之争
Java 与 .NET 的平台发展之争
程序员的鄙视链
程序员的鄙视链
2013年美国开发者薪资调查报告
2013年美国开发者薪资调查报告
程序员都该阅读的书
程序员都该阅读的书
什么才是优秀的用户界面设计
什么才是优秀的用户界面设计
如何成为一名黑客
如何成为一名黑客
初级 vs 高级开发者 哪个性价比更高?
初级 vs 高级开发者 哪个性价比更高?
老程序员的下场
老程序员的下场
漫画:程序员的工作
漫画:程序员的工作
中美印日四国程序员比较
中美印日四国程序员比较
程序员最害怕的5件事 你中招了吗?
程序员最害怕的5件事 你中招了吗?
团队中“技术大拿”并非越多越好
团队中“技术大拿”并非越多越好
不懂技术不要对懂技术的人说这很容易实现
不懂技术不要对懂技术的人说这很容易实现
写给自己也写给你 自己到底该何去何从
写给自己也写给你 自己到底该何去何从
程序员眼里IE浏览器是什么样的
程序员眼里IE浏览器是什么样的
每天工作4小时的程序员
每天工作4小时的程序员
程序员和编码员之间的区别
程序员和编码员之间的区别
Google伦敦新总部 犹如星级庄园
Google伦敦新总部 犹如星级庄园
总结2014中国互联网十大段子
总结2014中国互联网十大段子
我跳槽是因为他们的显示器更大
我跳槽是因为他们的显示器更大
旅行,写作,编程
旅行,写作,编程
看13位CEO、创始人和高管如何提高工作效率
看13位CEO、创始人和高管如何提高工作效率
软件开发程序错误异常ExceptionCopyright © 2009-2015 MyException 版权所有