JAVA代码规范笔记（上）

本文为《code conventions-150003》（JAVA代码规范）笔记。

文件组织

1、超过2000行代码的源文件将会比较难以阅读，应该避免。

2、每个Java源文件都包含单一的公共类或接口。如果私有类和接口与一个公共类有联系，可以把它们与这个公共类放在同一个源文件中。公共类必须是文件中的第一个类或接口。

3、JAVA源文件内容应该遵循以下顺序：

• 开头注释
• 包声明和引入语句，如：

import java.applet.Applet;
import java.awt.*;
import java.net.*;

• 类和接口的声明

4、开头注释

     所有的源文件在开头应该有一个C语言风格的注释，列出作者、日期和版权声明，并对程序的目的有一个简要的描述。例如：

/*
 *Classname
 *
 *Version info
 *
 *Copyright notice
 */

5、包声明和引入语句

    大多数Java源文件的第一条非注释语句都是包声明语句，接着是引入语句。如下：

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

6、类和接口声明

下表描述了类和接口声明的各个部分，以及它们出现的顺序。

	类/接口声明的各部分	备注
1	类/接口的文档注释	该注释所需包含的信息可以参见下面的文档注释
2	类/接口的声明
3	类/接口的实现注释(/*...*/),如果有必要的话	该注释应该包含所有与类或接口有关的信息，而这些信息又不适合作文档注释。
4	类（静态）变量	首先是类的公有(public)变量，然后是保护(protected)变量，之后是私有(private)变量。
5	实例变量	首先是公有的(public)，接着是保护的(protected)，之后是私有的(private)。
6	构造方法
7	方法	这些方法应该按功能，而非作用域或访问权限来分组。例如，一个私有的类方法可以在两个公有的实例方法之间，其目的是为了更利于代码的阅读与理解。

缩进
7、通常4个空格被作为缩进的一个单位。缩进使用的具体结构（是空格还是制表符）并无指明。一个制表符相当于8个空格（而非4个）。

8、行长度。

    避免一行代码超过80字符。因为它们在许多终端或工具都无法被很好的处理。

    注意：在文档中的例子行长度应该更短，一般不超过70字符。

9、换行

    当一条语句无法在一行写完，可以根据下面的一般原则来断句：

• 在一个逗号后断开
• 在一个操作符前断开
• 高级别的断开优先于低级别的断开
• 新的一行应该与上一句同一级别表达式的开头处对齐
• 如果以上的规则导致代码混乱，或使代码都堆挤在右边，可以代之以8个空格的缩进。

    下面是断开方法调用的一些例子：

function(longExpression1, longExpression2, longExpression3,
         longExpression4, longExpression5);
var = function1(longExpression1,
                function2(longExpression2,
                          longExpression3));

    下面两个例子是断开算术表达式的例子。第一个更好一点，因为断开处是在括号表达式外面，它是个较高级别的断开。

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

    下面是两个方法声明的缩进例子。第一个例子是常规情况。而第二个例子，如果使用常规的缩进方式，它会使第二行和第三行的代码太过于偏右，所以以缩进8个空格的方式代替。

//常规缩进
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
           Object andStillAnother) {
    ...
}
//以8个空格来代替，以避免缩进太严重
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {
    ...
}

    if语句的换行通常应该使用8个空格的规则，因为常规的缩进（使用4个空格）会使语句体比较难以阅读。例如：

//请勿使用这种缩进
if ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) { //BAD WRAPS
    doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
}
//使用这种缩进来代替
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}
//或这种缩进
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

    下面是三种格式化三目表达式的可行方法。

alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
                                 : gamma;
alpha = (aLongBooleanExpression)
        ? beta
        : gamma;

注释

10、Java程序有两类注释：实现注释和文档注释。实现注释就是在那些C++代码中见到的，使用/*...*/和//来限定的注释。文档注释是Java独有的，使用/**...*/来限定的注释。文档注释可以通过javadoc工具来提取成HTML文件。

实现注释是用来解释代码或详细说明实现的。文档注释通过实现自由的角度，来描述代码的使用说明，它被那些没必要有源代码在手上的程序员阅读。
注释通常用来给出代码的概述，和提供从代码本身不易得到的附加信息。注释应该只包含与阅读理解程序相关的信息。例如，相应的包如何被创建，或者它位于哪个目录，这样的信息就不应该包含在注释中。

注意：太频繁的注释有时也可以反映出代码质量欠佳。当你感觉不得不加上一个注释时，考虑一下重写代码并它更清晰。

注释不应该被封闭在一个用星号或其他字符画成的大框里。注释永远都不应该包含像制表符或退格符这样的特殊字符。

11、实现注释

程序可以有四种风格的实现注释：块注释，单行注释，尾端注释和行末注释。

12、块注释

块注释通常用于提供文件、方法、数据结构和算法的描述。块注释应当用在每个文件的开头和每个方法的前面。它们也可以用在其他地方，例如方法内部。在函数或方法内部的注释，应该和他们描述的代码有同样级别的缩进。

块注释前面应该有一个空行，来将它与其他代码分离开。块注释除了第一行之外，每一行都以一个星号“*”开头。

/*
 * Here is a block comment.
 */

块注释可以以 /*-开头，这样indent(1)就可以识别到它是一个块注释的开头，而不会去重格式化它。

/*
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */

注意：如果你不使用indent(1)，你就不必要在你的代码中使用/*-，或为其他人可能对你的代码运行indent(1)作出其他的让步。

13、单行注释

短的注释可以出现在一行内，并与其后面的代码有一样的缩进层级。如果一个注释无法在一行内写完，就应该使用块注释格式。一个单行注释前应该有一个空行。下面是Java代码里的单行注释的例子：

if (condition) {

    /* Handle the condition. */
    ...
}

14、尾端注释

非常短的注释可以出现在其描述的代码的同一行，但应该有足够的空白来分开代码与注释。如果有超过一个的短注释出现在一大块代码中，它们应该被缩进到同一个tab setting中（不会翻译，原文是they should all be indented to the same tab setting，大概意思是缩进到这些注释能对齐）。避免在每一行可执行代码都加上一个尾端注释的这种汇编语言风格的注释。

下面是Java代码尾端注释的一个例子：

if (a == 2) {
    return TRUE;            /* special case */
} else {
    return isprime(a);      /* works only for odd a */
}

15、行末注释

注释分隔符“//”开头的是不断换行的注释。它可以用来注释掉整行或一行中的一部分。它一般不用于连续多行的文本注释，但可以被用来注释掉连续多行的代码段。下面是所有三种风格的例子：

if (foo > 1) {
    // Do a double-flip.
    ...
}
else
    return false; // Explain why here.

//if (bar > 1) {
//
//    // Do a triple-flip.
//    ...
//}
//else
//    return false;

16、文档注释

若想了解更多详情，参见“How to Write Doc Comments for Javadoc”，其中包含了文档注释标记的信息（@return,@param,@see）：

http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

关于文档注释和javadoc的更多信息，参见javadoc主页：

http://java.sun.com/products/jdk/javadoc/

文档注释描述Java的类、接口、构造器、方法和字段。每个文档注释都置于注释分隔符/**...*/中，每个API对应一个注释。这个注释应该只出现在声明之前：

/**
 * The Example class provides ...
 */
class Example { ...

注意类和接口是不缩进的，而它的成员是缩进的。类和接口的文档注释的第一行（/**）是不缩进的，其后的文档注释行的都各有一个空格的缩进（使星号垂直对齐）。成员，包括构造方法，其文档注释的第一行是4个空格的缩进，其后是缩进5个空格。

如果你需要给出有关类、接口、变量或方法的信息，而这些信息又不适合出现在文档中，可以在紧跟在声明之后使用块注释或单行注释。例如一个类实现的细节，就应该在紧跟在类声明之后的块注释中，而不是在这个类的文档注释中。

文档注释不应该被放在方法或构造器的定义块中，因为Java会将文档注释与其后面的第一个声明进行关联。