本文档主要用来对java编码规范方面的说明。
一 命名规范
1 基本的规则
- 字符集在26个英文字母、0到9的阿拉伯数字和下划线之中。Java中类、字段、方法、变量、常量尽量用字母表达，没有特别的理由不能用任何的其他字符。
- 命名需要有一定的意义，推荐采用问题域中的术语命名，使命名在一定程度上是自描述的。
- 命名尽量的短，如果命名太长，可以采用别名的方式，或者缩写来简化命名。缩写一定要有意义，而且需要在整个项目中维护这些缩写的意义。
- 名称缩写的规则（对于类名、字段名、变量名称、模块名称等适用）
- 删除所有的原音字母，压缩重复字母。如button,缩写为btn。
- 如发生命名冲突，则在某一缩写中保留原音。如batton,为了不与button冲突，缩写为batn。
- 不要用前导下划线，也不要在命名的末尾用下划线。
2 常量命名
- 所有的字符都必须大写。采用有意义的单词组合表达，单词与单词之间以“_”下划线隔开。
- 命名尽量简短，不要超过16个字符。
- 程序开发中最好不要直接对literal进行工作，最好引入常量方式应用；只有在特别的情况下才能使用， 如在for循环中初始化变量时可直接用-1,0,1这些常量。
public final int MAX_SIZE = 120;
public final int MAX_WIDTH = 100;
public final String PROPERTY_NAME= "menu";
3 变量命名
变量的命名包括实例变量，静态变量，函数参数的命名。
- 避免在命名中采用数字，除非命名意义明确，程序更加清晰，对实例变量的命名中不应该有数字。 变量名称是名词意义。
- 采用有符合问题域意义的单词或单词组合。第一个单词全部小写，后续的每个单词采用首字母大写，其余小写(特殊单词除外，如URL)。
- 命名尽量简短，不要超过16个字符。
- 除了生命周期很短的临时变量外，避免采用单字符作为变量名，实例变量的命名不要用单字符。常用的单字符变量如整型用 i、j、 k、 m、 n字符型用c、d、 e，坐标用x、y、z。
- 在某些情况下，变量可能需要加上类型前缀，所有的类型前缀必须是小写，他与变量名称的实体部分没有任何间隔，实体部的每个单词都是首字母大写，其余字母小写（特殊单词除外如URL）,一般的类型前缀如下：
| 类型前缀 | 类型 | 例子 |
|---|---|---|
| str | 字符串(String, StringBuffer) | strFileName |
| ary | 数组 | aryName |
| conn | 连接 | connActiveConnection |
| stmt | Statement | stmtFindUser |
| rs | Resultset | rsUsers |
| col | Collection | colNames |
| msg | 消息 | msgText |
| err | 错误 | errCode |
| btn | 按钮 | btnSubmit |
在有特殊意义的情况下，不推荐采用前缀，而是推荐保持名称的语义。
public int width;
public String fileName;
public static ApplicationContext context;
4 方法命名
命名多数为动词结构。
- 采用有符合问题域意义的单词或单词组合。第一个单词采用小写，后续的每个单词采用首字母大写，其余小写（特殊字除外如URL），没有特别理由不用下划线作为分隔符。
- 在Java中对属性方法命名遵循JavaBean的标准：
- getter方法： get+属性名, 对boolean型采用is+属性名，有些特定的属性名用has, can代替is可能更好。
- setter方法： set+属性名。
- 构造方法的命名与类名一致。
String getName();
string isStopped();
void connect();
5 类和接口的命名
- 采用有符合问题域意义的单词或单词组合，每个单词的首字母大写，其余字母小写（特殊字除外如URL）。
- 接口的第一个字符采用。
//std为Standard的缩写
public class Fiugrepublic interface IFiugreContainerpublic class StdFigure
6 包的命名
- 包名所有的字符都为小写；
- 两个不同业务的包之间不要双向依赖,可以单向依赖；
- 采用逻辑上的层次结构，从而减少依赖；
- 包（package）的层次格式一般：“com.xxx51job.项目.模块（层）. …”的形式；xxx为项目简写
二 代码格式
1 注释类型
在 Java 程序中，一般有三种注释方式，如下表所示，可以根据其特点和用法在程序中充分使用。
| 注释类型 | 用法 |
|---|---|
| 文档格式 | 文档注释直接写在类、接口、成员函数和属性前面。可以通过javadoc工具生成文档。 |
| 单行注释 | 用来描述简单信息 |
| 多行注释 | 用来描述算法等多行文字 |
2 注释内容
- Action、Service、Entity中的全局变量和局部变量必须注释其具体含义。
- 对于类、接口以及方法的功能要有明确的文档注释。
- 较为重要的算法或关键的、复杂的处理环节、流程要有明确的注释，要在方法签名的注释中说明主要逻辑，并在方法体中注释逻辑细节。
- mapAction中的方法跳转要有注释：
3 注释格式
在注释中，遵循 JavaDoc定义的标签和格式，如下表所示，以便可以用JavaDoc生成格式标准、美观的联机文档。
系统简称中的代码如果是由框架自动生成的方法，系统会自动加上一些注释，格式如下
注：如果自己写的方法需要自己加上相关的注释。
4 注释规范
在编写java代码时，必须写好注释，这对于日后代码的可读性、可维护性至关重要。
Java代码的注释，需要遵循以下要求。
- 每个类，必须写好类的文档注释，注释内容要能够讲清楚类的总体功能和设计思想。
- 每个接口，必须写好接口的文档注释，注释内容要能够讲清楚接口的总体功能和作用。
- 每一个方法，必须写好方法的文档注释，即使是私有方法，也该如此。如果方法中包含参数、返回值、显式异常抛出，必须在文档注释中写明。如果一个方法是对接口的实现，那么详细的方法文档注释应该写在接口类的方法中，实现类方法应该通过 @see 指引过去特殊引用代码加@code标识。
- 类的属性，必须写好文档注释，说明该属性的含义和用途。
- 方法的内部实现，需要写好实现注释。衡量标准是将方法中的逻辑实现步骤写清楚，每个逻辑块都必须写有注释。如果类的内部实现只有简单的一两行代码，内部的实现注释可以不写。
- 注释的语句行不宜过长，可通过换行或者加
标签换下行方式书写显示。
- 对于必须实现，而尚未实现的功能，使用 //TODO 标记注释。
- 对于需要修正的bug，使用 //FIXME 标记注释。
- 系统试运行后的代码修改，请在修改代码段的开始注明修改日期、修改人、修改原因，以便他人查看。（虽然配置管理的历史信息中可以比较，但建议这样做，这样更直观）
所有类和方法都必须有注释（接口和实现类同时存在的话，把接口的注释写清楚，service里面的业务逻辑需要加必要的注释。），注释一定要清晰易读。如果类或者方法是从旧框架中迁移过来，必须使用@引用原有旧代码。
三 文件组织
每个文件包含一个单一的公有类（class）或接口（interface）。当私有类或接口与该公有类有必然的联系时，可以把他们放入同一源文件中。此时，公有类或接口应当是源文件中第一个类或接口。
1 书写顺序和规范
Java源代码文件按如下顺序书写：
- 开头的实现注释：可选，非javadoc注释。内容包括类版权信息，或其他不需要放入javadoc的类、接口说明。
- package。
- import：不推荐使用星号，须每个引用到的类分别import，这样有助于调试，并可在一定程度上避免bug的出现。在Eclipse中，可以使用快捷键 Ctrl+Shift+O 轻松实现自动import，在IntelliJ IDEA中可以通过Settings→Editor→General→Auto Import然后勾选Add unambiguous imports on the fly以及Optimize imports on the fly来实现自动导包。
- 类或接口的文档注释：必须，使用javadoc注释。
- 类或接口申明。
- 类静态成员属性：必须给出属性文档注释。
- 类非静态成员属性：必须给出属性文档注释。
- 类构造方法：必须给出构造方法的文档注释。
- 类或接口方法：必须给出方法的文档注释。
四 代码优化
1 代码大小
- 每个java文件的行数不要超过2000行，尽量控制在1000行以内，避免“上帝类”的产生。当一个类的行数超过1000行时，就是要注意了，是不是有变成“上帝类”的可能性了。
- 每个方法尽量的保持在200行的代码量以内，不能超过500行。尽量将一些逻辑实现，尤其是可复用的逻辑实现，分离到不同的方法中。
- 一个方法行数比较多时，请使用空行来分隔不同的逻辑块，再配以注释，提高程序的可读性。
2 方法
- 尽量保持最少的public method数量，太多的public method会引起类的误读而破坏OO封装原则。
- 在有可能的情况下，请尽量重用方法而不要自己创建。尽量保持系统中方法实现的单一性，以便能加强维护。
- 请严格的依照JavaBean的统一方式来写属性访问getter、setter方法，否则在java的反射机制实现时，会有问题。Eclipse和IDEA都提供了很好的自动创建功能。
- 方法调用的速度比较，从快到慢排列： static < final < instance method < interface method < synchronized。
- finalize方法尽可能避免使用。
- 避免方法多层嵌套，不利于可读性及维护性
3 属性和变量
- 公有类（public class）应该尽量不包含公有属性（public attribute），除非是公有的静态final属性（public static final attribute）。一般属性请使用私有（private attribute），然后对外通过共有的get和set方法访问。
- 避免在同一个类中调用方法（get或set）来设置或调用类共有属性。
- 尽可能的使用静态变量。如果类中的变量不会随他的实例而变化，就可以定义为静态变量，从而使他所有的实例都共享这个变量。
- 不要在代码中进行具体数值硬编码形成“魔法值”，把它定义为静态常量或者统一规划到枚举类中，然后在代码中引用。
- 请将运行环境变量信息配置在配置文件或数据库中。不可以在代码中直接写死运行环境配置值。比如数据库连接信息等。
- 尽量使用接口申明属性和变量。
如果没有特别的理由，那么对于参数、返回值、变量、属性的声明，都应该通过接口类型而不是具体类。通过接口引用对象，使程序能够接受不同的实现，从而变得更加灵活。因此请养成下面的习惯：
Map map = new HashMap();
List list = new ArrayList();
当然，如果没有合适的接口存在，或者程序确实需要依赖某个特定类的特定实现，那么使用具体类来引用一个对象是完全可以接受的。
- 在方法中使用局部变量，一定要确定变量赋值的唯一性。否则，代码将难以维护，形成歧义，而且是隐含bug的温床。
| 推荐的 | 不推荐的 |
|---|---|
| int nbrClient; int nbrProduct; nbrClient = getNbrClient(); nbrProduct = getNbrProduct(); | int nbrClient nbrClient = getNbrClient(); nbrClient = getNbrProduct(); |
4 代码格式
- 每行申明一个变量，下面格式则不推荐使用：
int level, size; - 不同类型的声明应放在不同的行，下面的格式是不正确的：
int foo, fooarray[]; - 每一行至多包含一个Statement，下面的格式是不正确的：
argv++; argc--;
Eclipse和IDEA的Format操作可以避免这种写法，不过要养成良好的习惯。
5 字符串处理
- 避免使用多个“+”号来进行数据串的合并这样的速度会很慢，请使用StringBuffer来做这件事情。如果只是一次或连词的字符串连接，或是调试信息的输出，允许使用“+”号，使得代码看起来更加直观。
- 在使用equals和equalsIgnoreCase方法判断两个字符串类型操作数是否相等时，如果两个操作数之中有一个为字符串常量，应该将它置于点操作符“.”的左边，用常量调用equals方法，将变量放在点操作符的右边。这样做的好处在于，程序员在使用equals和equalsIgnoreCase方法时，可以不必先判断变量操作数是否为null从而引起NPE异常。例如：
if ("anConstant".equals(value)) {// ... }
6 循环
- 请不要使用goto语句。
- 当使用循环的时候，请尽量不要直接在条件判断里面使用方法，例如：
| 推荐的 | 不推荐的 |
|---|---|
| int n = myList.size(); for (int i = 0; i < n; i++) { instructions; } | for (int i = 0; i < myList.size(); i++) { instructions; } |
7 switch语句
- 在任何的情况下，都必须在最后写上default语句,且每个case处理后都需要加break。如果不加break那么程序会按顺序往下执行，而不是跳出switch。
switch (condition) {
case ABC:
instruction;
break;
case DEF;
instruction;
break;
case XYZ;
instruction;
break;
default:
instruction;
break;
}
8 异常
JAVA语言中提供了try/catch来方便用户捕捉异常，进行异常的处理。但是如果使用不当，也会给JAVA程序的性能带来影响。因此，要注意以下三点。
- 避免对应用程序的逻辑使用try/catch ，如果可以用if、while等逻辑语句来处理，那么就尽可能不用try/catch语句。
- 重用异常，在必须要进行异常的处理时，要尽可能的重用已经存在的异常对象。因为在异常的处理中，生成一个异常对象要消耗掉大部分的时间。
- 在DAO层抛出的异常,在Service层进行catch,并抛出业务层的异常，ServiceException，在业务层抛出的异常，在Action或controller层catch，并显示在页面上，如果是Ajax方法，通过返回定义的异常规则，例如error_1，在JSP显示对应的异常信息。
9 日志和调试信息
- 不要直接的使用System.out或者System.err或者Exception的printStackTrace()方法打印出调试信息或Exception。可以使用Apache Log4J、slf4J来实现日志打印。
- 日志打印需使用统一的日志框架如log4j、logback且打印时最好将必要的入参、出参、以及重要的调试信息打印到日志文件以方便在发生异常错误时查询。
10 java.util包的使用注意
- 避免使用java.util包里面的java.util.Vector和java.util.Hashtable，因为这两个类是synchronized的，比不是synchronized的容器类速度会慢很多，当在单线程的情况下请使用java.util.ArrayList（接口是：java.util.List）和java.util.HashMap（接口是java.util.Map）。
6081
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
