java code specification

This is an old version of this page. You can view the most recent version or browse the history.

1 简介

对于软件开发遵循统一的规范，有利于增强代码的可读性，同时防范错误，更好的发挥所使用的语言的优点，提高工作效率。所以我们制定此编程规范，指导公司的编码活动。本规范适用于公司各个使用Java作为开发语言的项目，作为源程序编写的规范，必须遵守。使用其他语言所编写的程序，比如Perl，在不和所使用的语言冲突的情况下，可以参考本规范的要求来编写源程序。

参考资料

文档名称	作者	发布日期
《Rational Unified Process 2000》	Rational Software Corporation
《C++编程规范》	摩托罗拉中国公司
《高质量C语言编程》	林锐
《Java编程规范》	Sun

2 文件和目录

2.1 文件使用统一而且通用的后缀名

java程序的源文件： .java
二进制文件： .class
AspectJ源文件: .aj

2.2 文件名要清晰、精炼、避免冲突

可以用公共前缀对文件分组，但是要防止名字过长和冗余信息过多。在一个项目中，遵循统一的文件名命名规则。

2.3 文件/目录名字字符集选择

只能使用以下字符集：[A-Za-z0-9_-]
包名只能用小写字符、数字和“.”。
类名第一个字符必须大写。

2.4 单个的文件建议不超过1000行

这项不作为强制条件执行，但一个类超过1000行，很有可能这个类的内聚性有问题。

2.5 单个的函数建议不超过100行，但一定不要超过200行

3 文件组织

每个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件（不建议）。公共类必须是这个文件中的第一个类或接口。 Java源文件还遵循以下规则：

文件头注释
包和引入语句
类和接口声明

3.1 文件头注释

参见注释里的文件头注释。

3.2 包和引入语句

在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。例如：

package java.awt; 
import java.awt.peer.CanvasPeer;

3.3 类和接口说明

类/接口申明包括以下几部分：

1. 类/接口文档注释
2. 类或接口的声明
3. 类/接口实现的注释（该注释应包含任何有关整个类或接口的信息，而这些信息又不适合）
4. 类的(静态)变量
5. 实例变量
6. 构造器
7. 方法

3.4 变量申明的次序

变量申明的次序如下：

1. 先静态后实例变量
2. 先public后protected再private

4 排版

4.1 缩进

4个空格作为缩进排版的一个单位，缩进也可以使用TAB键。

4.2 在程序适当的地方加入空行

在以下地方应该是用空行分开：

1. 方法之间应该用空行分开；
2. 一组局部变量声明和代码之间用空行分开；
3. 用空行将代码按照逻辑片断划分；
4. 除非方法非常简单（如只有一两条语句），否则方法返回语句和其他语句用空行分开；
5. 每个类声明之后应该加入空行同其他代码分开；

4.3 换行

每一行不要超过120个字符，当一个表达式无法容纳在一行内时，可以依据如下规则分行书写：

1. 在一个逗号后面断开
2. 在一个操作符前面断开
3. 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开
4. 新的一行应该与上一行同一级别表达式的开头处对齐
5. 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进4个空格。

示例:

以下是断开方法调用的一些例子:

foo.sum(longExpression1, longExpression2, longExpression3, 
           longExpression4, longExpression5); 

var = foo.sum(longExpression1, 
                 foo.sum(longExpression2, 
                                        longExpression3));

以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开，后者不建议采用。

longName1 = longName2 * (longName3 + longName4 - longName5) 
                + 4 * longname6; 

longName1 = longName2 * (longName3 + longName4 
                 - longName5) + 4 * longname6;

以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进4个空格。

//常规情形 
public synchronized  void invoke (int anArg, Object anotherArg,
                                  String yetAnotherArg, 
                                  Object andStillAnother) 
{ 
    ... 
} 
//缩进4个空格以免太靠右 
public synchronized  void invoke (int anArg, Object anotherArg, 
String yetAnotherArg, Object andStillAnother)
{ 
    ... 
}

4.4 一行只写一条语句

示例:

如下例子不符合规范:

rect.length = 0;  rect.width = 0;

应如下书写:

rect.length = 0;
rect.width = 0;

4.5 if for do while等语句自占一行，其后无论执行语句多长，都应该使用{}

例外的情况是：如果存在多个if…else…语句并列，则else可以和if放在同一行。

示例：

如下的写法不合规范：

if (0 == a) return null;

应该这样写：

if (0 == a) 
{
    return null;
}

4.6 右大括号}要单独占一行，左大括号不作结强制规定，但在单个文件中要统一

右大括号要单独占一行，并且和它的控制语句有相同的缩进。但也有例外：

* 1. do-while循环中，}和while放在一行,应该按照以下格式书写：

do
{
    i++;
} while (i < 100);

4.7 代码行之间应该留有适当的空格

代码行内应该适当的使用空格，具体地说来：

1. 关键字之后要留空格。象final、virtual、synchronized、case 等关键字之后至少要留一个空格，否则无法辨析关键字。象if、for、while 等关键字之后应留一个空格再跟左括号‘（’，以突出关键字。
2. 方法名之后不要留空格，紧跟左括号‘（’，以与关键字区别。
3. ‘（’向后紧跟，‘）’、‘，’、‘;’向前紧跟，紧跟处不留空格。
4. ‘，’之后要留空格，如function(int x, int y, int z)。如果‘;’不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。
5. 值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”、“?”等二元操作符的前后应当加空格。
6. 一元操作符如“!”、“~”、“++”、“--”等前后都不加空格。
7. 象“［］”、“.”这类操作符前后不加空格。

示例,应该按照以下的格式书写：

void foo()
{
    //…
}

或者：

if (0 == i)
{
    //…
}

或者：

foo.bar

或者

foo[bar]

或者：

i++;
!i;

或者

i += 9;
a * b;

等等

5 命名规范

5.1 命名基本规范

命名应该遵守以下基本原则：

1. 命名要简单清楚，避免使用引起误解的词汇，避免使用模糊的缩写，长度不要超过25个字符
2. 命名必须使用英文单词，不能使用汉语拼音
3. 命名用可发音的名字
4. 选择通用词汇并且贯穿始终
5. 命名要通俗易懂 另外，命名还应该做到：
1. Package 的名字应该都是由一个全部小写单词组成。
2. Class 的名字必须由大写字母开头而其他字母都小写的单词组成
3. 变量的名字必须用一个全部小写的单词开头。后面的单词用大写字母开头，其余都小写。
4. 参数的名字必须和变量的命名规范一致。
5. 数组应该总是用下面的方式来命名：

byte[] buffer;

而不是：

byte buffer[];

6. 使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：

setCounter(int count)
{ 
    this. count = count; 
}