Java语言规范

Java语言规范

📌翻译自官方文档Code Conventions for the Java TM Programming Language

---

文档目录

• Java语言规范
• 1.为什么有代码约定?
• 2.文件名
• • 2.1文件后缀
  • 2.2 常用文件名
• 3.文件组织
• • 3.1 Java 源文件
  • • 3.1.1 开始注释
    • 3.1.2 包和导入语句
    • 3.1.3 类和接口声明
• 4.缩进
• • 4.1 行长度
  • 4.2 换行
• 5.注释
• • 5.1 实现注释格式
  • 5.1.1 块注释
  • 5.1.2 单行注释
  • 5.1.3 尾随注释
  • 5.1.4 行尾注释
  • 5.2 文档注释
• 6.声明
• • 6.1 每行数量
  • 6.2 初始化 Initialization
  • 6.3 放置 Placement
  • 6.4 类和接口声明
• 7.语句
• • 7.1 简单语句
  • 7.2 复合语句
  • 7.3 返回 语句
  • 7.4 if、if-else、if-if-if 语句
  • 7.5 语句
  • 7.6 而语句
  • 7.7 do-while 语句
  • 7.8 switch 语句
  • 7.9 try-catch 语句
• 8.空白
• • 8.1 空白行
  • 8.2 空白
• 9.命名约定
• 10.编程实践
• • 10.1 提供对实例和类变量的访问
  • 10.3 常量
  • 10.4 变量赋值
  • 10.5 杂项做法
  • • 10.5.1 括号
    • 10.5.2 返回值
    • 10.5.3 条件运算符中"？"之前的表达式
    • 10.5.4 特别评论
• 11.代码示例
• • 11.1 Java 源文件示例
• 总结

1.为什么有代码约定?

1.软件生命周期成本的 80% 用于维护
2.几乎没有任何软件是由原作者在其整个生命周期中维护的。
3.代码约定提高了软件的可读性，使工程师能够更快、更彻底地理解新代码。
4.如果您将源代码作为产品发布，则需要确保其包装良好且与您创建的任何其他产品一样干净。

2.文件名

2.1文件后缀

File Type	Suffix
Java source	.java
Java bytecode	.class

2.2 常用文件名

文件名	用处
GNUmakefile	生成文件的首选名称。我们用gnumake来构建我们的软件。
README	汇总特定目录内容的文件的首选名称。

3.文件组织

3.1 Java 源文件

每个 Java 源文件都包含一个公共类 public class 或接口 interface。
当私有类 private classes 和接口 interfaces与公共类 public class 关联时，可以将它们放在与公共类 public class 相同的源文件 the same source file 中。
公共类应该是文件中的第一个类或接口。

3.1.1 开始注释

/*
 * Classname 类名
 * 
 * Version information 版本信息
 *
 * Date 日期
 * 
 * Copyright notice 版权记录
 */

3.1.2 包和导入语句

package java.awt; //包名

import java.awt.peer.CanvasPeer; //导包

3.1.3 类和接口声明

	类/接口声明的一部分	笔记
1	类/接口文档注释 （/**…*/)	有关此注释中应包含的内容的信息，请参阅第 9 页上的"文档注释"。
2	类class或接口interface语句
3	类class/接口interface实现implementation注释comment（ /…/），如有必要的话	此注释应包含不适合类/接口文档注释的任何类范围或接口范围的信息。
4	类 class（ static）variables变量	首先是类class variables 变量，然后是 protected，然后是包级别 package level（无访问修饰符, 然后是 private。
5	实例变量 Instance variables	首先是 public, 然后是protected，然后是 包级别 package level（无访问修饰符)，然后是 private。
6	构造函数 Constructors
7	方法 Methods	这些方法应按功能分组，而不是按范围或可访问性分组。例如，私有类方法可以位于两个公共实例方法之间。目标是使阅读和理解代码更容易。

4.缩进

应使用四个空格作为缩进单位。
缩进的确切构造（空格与制表符）未指定。
必须每隔 8 个空格（而不是 4 个空格）精确设置一个选项卡。

4.1 行长度

🎈当表达式不适合单行时，请根据以下一般原则将其断开：

1.逗号后换行。
2.在操作之前中断。
3.使用更高级别的换行，而不是更低级别的换行。（如例二）
4.将新行与表达式的开头对齐，位于前一行的同一级别。
5.如果上述规则导致代码混乱或代码被挤压到右边距，只需缩进8个空格即可。

Here are some examples of breaking method calls:

下面是中断方法调用的一些示例：

someMethod(longExpression1, longExpression2, longExpression3, 
        longExpression4, longExpression5);
 
var = someMethod1(longExpression1,
                someMethod2(longExpression2,
                        longExpression3));

Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.

以下是打破算术表达式的两个示例。
第一种情况更可取，因为中断发生在括号表达式之外，该表达式位于较高级别。

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

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 使用这种（8 空格）😉
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
} 

//OR USE THIS 或者使用这种
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

4.2 换行

三元表达式格式的三种换行方法：

alpha = (aLongBooleanExpression) ? beta : gamma;  

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;  

alpha = (aLongBooleanExpression)
        ? beta 
        : gamma;

5.注释

Java 程序可以有两种注释：实现注释和文档注释。实现注释是在C++中找到的注释，由 /*...*/ 和 // 分隔。文档注释（称为"文档注释"）仅支持 Java，并由 /**...*/ 分隔。文档注释可以使用 javadoc 工具提取到 HTML 文件中。

5.1 实现注释格式

程序可以有四种样式的实现注释：块、单行、尾随和行尾。

5.1.1 块注释

块注释用于提供文件、方法、数据结构和算法的描述。
可以在每个文件的开头和每个方法之前使用块注释。
它们也可以在其他地方使用，例如在方法中， 函数或方法中的块注释应缩进到与它们描述的代码相同的级别。

块注释前面应有一个空行，以将其与代码的其余部分区分开来。

/*
 * Here is a block comment.
 */

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

5.1.2 单行注释

短注释可以出现在缩进到后续代码级别的单行上。
如果注释不能用一行写，它应该遵循块注释格式（参见第5.1.1节）。
单行注释前面应有一个空行。下面是 Java 代码中单行注释的示例（另请参阅第 9 页上的"文档注释"）：

if (condition) {

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

5.1.3 尾随注释

非常短的注释可以与它们描述的代码出现在同一行上，
但应移动足够远以将它们与语句分开。
如果代码块中出现多个短注释，则它们都应缩进到同一选项卡设置中。

下面是 Java 代码中尾随注释的示例：

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

5.1.4 行尾注释

注释分隔符可以注释掉一整行，
也可以只注释掉部分行。
它不应该用于文本注释的连续多行;
但是，它可以在连续的多行中用于注释掉代码部分。
所有三种样式的示例如下：

if (foo > 1) {

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

5.2 文档注释

文档注释描述了 Java 类、接口、构造函数、方法和字段。
每个文档注释都设置在注释分隔符内，每个类、接口或成员都有一个注释。
此注释应出现在声明之前：/**...*/

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

请注意，顶级类和接口不缩进，而其成员缩进。
类和接口的文档注释 （/**） 的第一行不缩进;
后续的文档注释行每个都有 1 个缩进空间（垂直对齐星号）。
成员（包括构造函数）在第一个文档注释行中有 4 个空格，之后有 5 个空格。

Doc 注释不应位于方法或构造函数定义块中，
因为 Java 将文档注释与注释之后的第一个声明相关联。

6.声明

6.1 每行数量

int level; // indentation level
int size;  // size of table

//优先于
int level, size;

//不要在同一行上放置不同的类型。例：
int foo, fooarray[]; //WRONG!

/*
 * 注意：上面的示例在类型和标识符之间使用了一个空格。
 * 另一种可接受的替代方法是使用选项卡（tabs），例如：
 */
int     level;          // indentation level
int     size;            // size of table
Object  currentEntry;    // currently selected table entry

6.2 初始化 Initialization

尝试在声明局部变量的位置初始化局部变量。
不初始化声明变量的唯一原因是初始值是否依赖于首先发生的某些计算。

6.3 放置 Placement

仅将声明放在块的开头。
（ 块是用大括号"{"和"}"括起来的任何代码。）不要等到第一次使用变量时才声明它们;
它可能会使粗心大意的程序员感到困惑，并妨碍范围内的代码可移植性。

void myMethod() {
    int int1 = 0;         // beginning of method block

    if (condition) {
        int int2 = 0;     // beginning of "if" block
        ...
    }
}
</blockquote>

该规则的一个例外是for循环，在 Java 中可以在for语句中声明:

for (int i = 0; i < maxLoops; i++) { ... }
</blockquote>

避免使用隐藏较高级别声明的本地声明。
例如，不要在内部块中声明相同的变量名：

int count;
...
myMethod() {
    if (condition) {
        int count = 0;     // AVOID!
        ...
    }
    ...
}

6.4 类和接口声明

编写 Java 类和接口时，应遵循以下格式规则：

class Sample extends Object {
    int ivar1;
    int ivar2;

    Sample(int i, int j) {
        ivar1 = i;
        ivar2 = j;
    }

    int emptyMethod() {}

    ...
}

未完待续。。。

7.语句

7.1 简单语句

7.2 复合语句

7.3 返回 语句

7.4 if、if-else、if-if-if 语句

7.5 语句

7.6 而语句

7.7 do-while 语句

7.8 switch 语句

7.9 try-catch 语句

8.空白

8.1 空白行

8.2 空白

9.命名约定

10.编程实践

10.1 提供对实例和类变量的访问

10.3 常量

10.4 变量赋值

10.5 杂项做法

10.5.1 括号

10.5.2 返回值

10.5.3 条件运算符中"？"之前的表达式

10.5.4 特别评论

11.代码示例

11.1 Java 源文件示例

---

总结

提示：这里对文章进行总结：