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，它只是自动化工作的一部分。
英文：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，它只是自动化工作的一部分。