JAVA 编码规范
1 介绍(Introduction)
1.1 为什么要有编码规范
编码规范对于程序员而言尤为重要,有以下几个原因:
- 一个软件的生命周期中,80%的花费在于维护
- 几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护
- 编码规范可以改善软件的可读性,可以让程序员尽快而彻底地理解新的代码
- 如果你将源码作为产品发布,就需要确任它是否被很好的打包并且清晰无误,一如你已构
建的其它任何产品
为了执行规范,每个软件开发人员必须一致遵守编码规范。
2.文件名
这部分列出了常用的文件名及其后缀。
2.1 文件后缀
Java 程序使用下列文件后缀
文件类别 文件后缀
Java 源文件 .java
Java 字节码文件 .class
2.2 常用文件名
Java 程序使用下列文件后缀
文件类别 文件后缀
Java 源文件 .java
Java 字节码文件 .class
3.文件组织
一个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。超过 2000 行的
程序难以阅读,应该尽量避免。"Java 源文件范例"提供了一个布局合理的 Java 程序范例。
3.1JAVA 源文件
每个 Java 源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联,
可以将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。
Java 源文件还遵循以下规则:
- 开头注释(参见"开头注释")
- 包和引入语句(参见"包和引入语句")
- 类和接口声明(参见"类和接口声明")
3.1.1 开头注释
所有的源文件都应该在开头有一个 C 语言风格的注释,其中列出类名、版本信息、日期和
版权声明:
/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/
3.1.2 包和引入语句
在多数 Java 源文件中,第一个非注释行是包语句。在它之后可以跟引入语句。例如:
package java.awt;
import java.awt.peer.CanvasPeer;
3.1.3 类和接口说明
下表描述了类和接口声明的各个部分以及它们出现的先后次序。参见"Java 源文件范例"中一
个包含注释的例子。
类/接口声明的各部分 注解
1 类/接口文档注释(/**……*/) 该注释中所需包含的信息,参见"文档注释"
2 类和接口的声明
3 类/接口实现的注释(/*……*/)如果有必要的话 该注释应包含任何有关整个类或接口的信息,
而这些信息又不适合作为类/接口文档注释。
4 类的(静态)变量 首先是类的公共变量,随后是保护变量,再后是包一级别的变量(没有访
问修饰符,access modifier),最后是私有变量。
5 实例变量 首先是公共级别的,随后是保护级别的,再后是包一级别的(没有访问修饰符),
最后是私有级别的。
6 构造器
7 方法 这些方法应该按功能,而非作用域或访问权限,分组。例如,一个私有的类方法可
以置于两个公有的实例方法之间。其目的是为了更便于阅读和理解代码。
4.缩进排版
4 个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格 vs. 制表符)。
一个制表符等于 8 个空格(而非 4 个)。
4.1 行长度
尽量避免一行的长度超过 80 个字符,因为很多终端和工具不能很好处理之。
注意:用于文档中的例子应该使用更短的行长,长度一般不超过 70 个字符。
4.2 换行
当一个表达式无法容纳在一行内时,可以依据如下一般规则断开之:
- 在一个逗号后面断开
- 在一个操作符前面断开
- 宁可选择较高级别(higher-level)的断开,而非较低级别(lower-level)的断开
- 新的一行应该与上一行同一级别表达式的开头处对齐
- 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边,那就代之以缩进 8 个空格。
以下是断开方法调用的一些例子:
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));
以下是两个断开算术表达式的例子。前者更好,因为断开处位于括号表达式的外边,这是个
较高级别的断开。
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; //PREFFER
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; //AVOID
以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二
行和第三行移得很靠右,所以代之以缩进 8 个空格
//CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother){
...
}
//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
if 语句的换行通常使用 8 个空格的规则,因为常规缩进(4 个空格)会使语句体看起来比较费
劲。比如:
//DON'T USE THIS INDENTATION
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //BAD WRAPS
doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
}
//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
这里有三种可行的方法用于处理三元运算表达式:
alpha = (aLongBooleanExpression) ?
beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;
5.注释
Java 程序有两类注释:实现注释(implementation comments)和文档注释(document comments)。
实现注释是那些在 C++ 中 见 过 的 , 使 用 /*...*/ 和 // 界 定 的 注 释 。 文 档 注 释 ( 被 称 为 "doc