java语言SUN公司标准编码规范

Java语言编码规范(Java Code Conventions)SUN标准

遵循编码规范的必要性

编码规范对于程序员而言尤为重要，有以下几个原因：

• 在其生命周期内, 软件的主要开支用于维护工作。
• 几乎没有任何一个软件, 其全生命周期都由最初的开发人员独自负责维护。
• 编码规范有助于提高软件可读性, 可以使程序员更快且全面地掌握新代码。
• 如果你要将源码发布为产品, 就必须确保它已经被良好打包和清晰无误地呈现出来, 如你之前构建的产品一样。

为了执行规范，每个软件开发人员必须一致遵守编码规范。每个人。

该文档反映了Sun Microsystems公司关于Java语言规范中编码标准的部分。主要贡献者包括以下人员：Peter King、Patrick Naughton、Mike DeMoney、Jonni Kanerva、Kathy Walrath以及Scott Hommel。

本文档现由Scott Hommel维护，有关评论意见请发至shommel@eng.sun.com

这部分列出了常用的文件名及其后缀。

Java程序使用下列文件后缀：

常用的文件名包括：

一个文件通常由通过空行分隔开的不同段落构成，并且每个段落可能包含可选的注释标记。面对拥有超过2000行代码的情况时，请尽量避免编写这样的复杂代码。在'Java源文件范例'一书中有一个编写得非常合理的Java程序实例。

遵循单个public基类或interface的规定，在一个Java源文件中通常只会定义一个这样的基元素类型base class或interface. 当私有类别与其他（可能多个）基元类型相关联时，则允许将这些关联类型与其共同的基础类型放置于同一个源代码模块中以提高组织效率. 且该基元类型必须位于该模块中最早声明的基元类型或其他相关类型的定义位置上以确保规范性.

Java源文件还遵循以下规则：

- 开头注释（参见"

第3章第1节第1小节 开始注释（Beginning Comments）第3章第1节第2小节 包及其导入语句（Package and Import Statements）第3章第1节第3小节 类与接口声明（Class and Interface Declarations）其中包含一个带有丰富注释的Java源文件示例

在源文件的最开始部分应添加一个具有C语言风格的注释文档，在此注释中明确列出类名、版本信息、编写日期以及版权声明等必要信息。

改写说明

下表描述了类和接口声明的各个部分以及它们出现的先后次序。参见"

第4章 缩进排版（Indentation） 第4节 缩进排版

四个空格通常被视为排版中的缩进单位。关于缩进的具体定义并未明确说明是使用空格还是制表符。换而言之,一个制表符相当于八个空格

尽量避免一行的长度超过80个字符，因为很多终端和工具不能很好处理之。

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

当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：

• 在逗号之后分隔
• 在操作符前进行分隔
• 更倾向于采用较高级别的(higher-level)分隔方式
• 新行应与上一行同级别的表达式起始位置对齐
• 若遵循上述准则后导致代码混乱或过于靠右，则建议采用缩进8个空格的方式进行调整。

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

我们可以观察两个具有算术运算中断的例子。前一种情况更为优异。由于断开位置处于括号运算的外部区域，在此情况下表现出较高的层次性。

以下列举了两种缩进方法的示例。第一种情况属于常规处理，在这种情况下无需额外操作即可满足需求。第二种情况如果采用传统缩进方式，则会导致后续行文字左移较多；因此建议将第二及第三行左部增加8个空格以确保排版整齐

if语句的换行一般采用8个空格的标准做法，这是因为常规缩进（4个空格）会导致代码块看起来不够直观。例如：

这里有三种可行的方法用于处理三元运算表达式：

Java程序有两种类型的标记：功能性的评论（implementation comments）与文档性评论（document comments）。功能性的评论常见于C++中，在其中它们通常以/* ... / 和 // 标识符限定。被称作"doc comments"的文档性评论专属于Java语言，并由/* ... */ 标识符限定。通过javadoc工具可将这些文档性评论转换为HTML格式文件。

注释可用于标注代码及其细节内容。基于无源码环境的概念阐述代码规范的一种标记语言具有易懂性特点。这样的一种标记语言便于那些无需完整代码库便能理解技术细节的人阅读和参考。

注释可用于概述整个代码结构，并补充代码未明确说明的功能。这些评论的作用不仅在于总结现有功能，还旨在为理解和执行程序提供额外的帮助。需要注意的是，在编写注解时应避免过于具体的细节描述，例如构建相关包的位置或路径等信息不在其中。

在代码中的注释部分中进行必要的解释是有帮助的做法，并非坏事。然而，在实际操作中应当尽量避免冗余的信息冗述——即不要在代码已有明确表达的基础上再重复说明同样的内容。过度依赖冗余标注可能会导致文档维护成本上升。因此，在编写技术文档时应当特别注意删除那些容易因代码更新而失效的具体标注内容

请注意：频繁出现的注释通常暗示着代码质量不高。如果你觉得不得不添加大量注解以提高可读性时，请考虑重新设计代码结构使其更加直观。

注释不能被放置在由星号或其他特殊符号绘制的框内。注释不能包含像制表符和回退符这样的特殊字符。

该程序采用四种注释风格：包括块式(block)、单行(single-line)、尾端(trailing)以及行末(end-of-line)。

块注释常被用来详细说明文件内容、程序中的操作步骤（如函数或类）、使用的数据格式以及算法逻辑。
在程序的不同部分（如主程序或函数）中，块注释通常放置于该部分的第一个位置，并且出现在每条函数定义之前。
除了这些主要位置外，在某些情况下（如函数体内），它们也会被使用。
对于位于功能或函数之内的块注释内容，则应与实际操作步骤保持一致。

块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：

块注释通常采用前缀‘/*-’作为标记。

请特别注意以下事项：若无特殊需求，则需在代码中标注indent(1)以避免潜在的问题出现。选择编码风格时，请权衡个人习惯与团队协作的需求

参见"

第5.1.2节介绍的是'单线注解'与'块状说明符'两种形式。\n\n应放置于前一个空白段落。\n\n以下展示了一个Java语言中的单一实例：

短注释可以在一行内呈现，并与后续代码保持相同的缩进程度。当一个注释无法完整书写于一行时，则应当采用块注释（参见""）。

5.1.3 行末说明... (Trailing Comments)
5.1.4 行尾标注... (End-of-Line Annotations)
5.2 技术文档说明... (Documentation Notes)
Java源文件范例

简短的注释可以在同一行上与它们所需描述的代码并列排列；然而需要适当的空间间隔来区分代码和注释.In the case of multiple brief annotations within a large block of code, their indentation should be consistent.

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

注释界定符"//"可以在Markdown中用来标注整行或部分文字以实现注释功能。
//通常被称为斜杠符号，在Markdown中用于标注整行或部分文字以实现注释功能。
它一般不用于连续多行的注解文本；
然而，
它也可以用来标注连续多行代码块。
以下是所有三种风格的例子：

在Markdown编辑器中，
使用斜杠"//"作为标记符，
可以对单个文字进行标注以达到备注的目的。
通常情况下，
这种标记符不会影响到对多行文本的标注效果；
然而，
它也可以被灵活应用到多个连续代码块段落的标注上。

注意：此处描述的注释格式之范例，参见"

如需进一步了解，请参见"How to Write Doc Comments for Javadoc"：其中包含了关于文档注释标记的相关信息（@return, @param, @see）。

http://java.sun.com/javadoc/writingdoccomments/index.html

若想了解更多有关文档注释和javadoc的详细资料，参见javadoc的主页：

http://java.sun.com/javadoc/index.html

文档注解释说Java中的类与接口及其相关构造器等核心元素的方法与字段（field）。每个这样的结构都由单独的一个标注来标识并放置于**/.../**之中的位置，并且这些标注应放置在声明之前：

遵循如下原则：顶层类与接口不在代码块内进行格式化；其中成员元素均需进行相应的格式化操作以确保可读性与一致性。具体而言：

• 其文档注释的第一行为非空格处理，并未进行缩进；
• 后续各行内容统一左移一位（便于星号对齐）。
  对于成员元素及其相关属性或方法：
• 第一行内容需左移四位；
• 后续各行内容统一左移五位。

当需要向文档外提供关于类、接口、变量或方法的具体信息时，请参考5.1.1条款或如图5.1所示的位置放置相关注释。例如通常会采用以下做法：将一个类如何实施其功能的详细信息置于紧跟在其声明之后的实现块注释中（见5.1），而不会置于文档注释中（见5.2）。

文档注释不建议放置在一个方法或构造器的定义块内，在Java中这会导致后续声明与文档注释产生关联。

6 声明(Declarations)6.1 每行声明变量的数量(Number Per Line)6.2 初始化(Initialization)6.3 布局(Placement)6.4 类和接口的声明(Class and Interface Declarations)7 语句(Statements)7.1 简单语句(Simple Statements)7.2 复杂语句(Complex Statements)7.3 返回语句(return Statements)7.4 条件判断结构(if, if-else, if-else-if-else条件判断结构)7.5 for循环(for循环)7.6 while循环(while循环)7.7 do-while循环(do-while循环)7.8 switch-case(switch-case结构)7.9 try-catch块(try-catch块)8 空白(White Space)8.1 空行(Blank Lines)[注：此处为原文内容]5.1.1"）或单行注释（参见"5.1.2"）之前
- 一个方法内的两个逻辑段之间用于提高可读性的分隔符

推荐一行一个声明，因为这样以利于写注释。亦即，

要优于，

int level, size;

不要将不同类型变量的声明放在同一行，例如：

请注意，在类型和标识符之间插入一个空白字符（如空格或制表符）是一种常用的做法

优先在声明局部变量的同时进行初始化，在这种情况下主要原因是因为变量的初始值基于之前的计算结果。

仅在一个区域内部进行变量 declaration（即每个区域指的是由大括号{}包围的一个独立的 code 块）。为了防止不够专注的程序员混淆概念并提高 code 在该作用域内的可移植灵活性，在首次引用某个 variable 之前就应该进行 declaration。

该规则的一个例外是for循环的索引变量

应避免在同一层次的局部变量声明中覆盖父级声明的变量，并确保内部代码块中的命名空间独立以避免冲突。例如，在编写嵌套代码结构时，请确保内部代码块中的变量命名与父级层次不同：int i = 1;这样的做法可能会导致错误或难以调试的结果。

当编写类和接口是，应该遵守以下格式规则：

- 左括号不应紧随方法名及其参数列表之前的空格
- 左大括号置于声明语句同行的行尾
- 右大括号置于新行并与对应声明语句对齐（除非该语句为空）；右大括号紧随左大括号后放置

- 方法与方法之间以空行分隔

每行至多包含一条语句，例如：

复合语句是包含在大括号中的语句序列，形如"{ 语句 }"。例如下面各段。

- 位于其中的语句应与复合语句缩进一格
- 左大括号"{"应放置在复合语句起始行的最后一行；右大括号"}"则需另起一行并与首行齐平
- 对于诸如if-else或for等控制结构中的所有单个或多个语句来说，使用大括号是可行的方案。它不仅简化了书写过程还能避免忘记添加必要的括号从而防止潜在的错误

在具有返回值的情况下,避免使用小括号(),除非它们通过某种方式使得返回值更加明显.例如:

if-else语句应该具有如下格式：

注意：if语句总是用"{"和"}"括起来，避免使用如下容易引起错误的格式：

一个for语句应该具有如下格式：

一个无内容的for循环（应包含初始化阶段、条件判断环节以及更新操作）应遵循以下结构：初始化阶段启动后自动执行；随后进行条件判断；最后执行更新操作。

在for语句的初始化或更新子句中使用逗号时应尽量避免因过多字段操作而导致性能下降。若有特殊需求则应在for循环之前（用于初始化字段）或在循环末尾（用于更新字段）单独执行相关操作。

一个while语句应该具有如下格式

一个空的while语句应该具有如下格式：

一个do-while语句应该具有如下格式：

一个switch语句应该具有如下格式：

每当一个case连续往下执行（由于没有break语句），通常应在break位置加入说明性注释。例如，在提供的示例代码中可以看到这样的标记：/*/ falls through

一个try-catch语句应该具有如下格式：

一个try-catch语句后面也可能跟着一个finally语句，在无论try代码块是否顺利完成的情况下都会被执行。

空行将逻辑相关的代码段分隔开，以提高可读性。

下列情况应该总是使用两个空行：

- 一个源文件的两个片段(section)之间
- 类声明和接口声明之间

下列情况应该总是使用一个空行：

- 两个方法之间
- 方法内的局部变量和方法的第一条语句之间
- 块注释（参见"

8.2 第八节 空白处(Blank Spaces)
9 第九章 命名标准(Naming Conventions)
10 第十章 编程准则(Programming Practices)
10.1 第十章第1节 提供对实例及类变量的访问权限(Providing Access to Instance and Class Variables)
10.2 第十章第2节 引用类变量及方法(Referring to Class Variables and Methods)
10.3 第十章第3节 常量(Constants)
10.4 第十章第4节 变量赋值(Variable Assignments)
10.5 第十章第5节 其他准则(Miscellaneous Practices)
10.5.1 圆括号(Parentheses) - 用于操作优先级
10.5.2 返回值(Returning Values) - 使用return语句退出函数
10.5.3 条件运算符"?"前的表达式(Expressions before '?' in the Conditional Operator) - 限定条件运算符适用范围
10.5.4 特殊注释(Special Comments) - 附加说明的部分
第十一章代码范例(Code Examples)
第十一章附录一 Java源文件范例(Java Source File Example) - 类与接口声明 以及 文档注释。

下列情况应该使用空格：

- 一个紧跟着括号的关键字应该被空格分开，例如：

需要注意的是，在方法命名与左括号之间不应放置空格以避免区分关键字与函数调用。

- for语句中的表达式应该被空格分开，例如：

- 强制转型后应该跟一个空格，例如：

遵循命名规范有助于提高程序的可读性；这进一步增强了程序的理解性。这些名称信息也能够揭示标识符的功能与作用；以便更好地理解代码的行为；例如；不管该名称代表的是一个常量包还是一个类；

| 包(Packages)| 一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166标准所指定的标识国家的英文双字符代码。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。| com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese |
| 类(Classes)| 命名规则：类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML)| class Raster;
class ImageSprite; |
| 接口(Interfaces)| 命名规则：大小写规则与类名相似| interface RasterDelegate;
interface Storing; |
| 方法(Methods)| 方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。| run();
runFast();
getBackground(); |
| 变量(Variables)| 除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。
变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。| char c;
int i;
float myWidth; |
| 实例变量(Instance Variables)| 大小写规则和变量名相似，除了前面需要一个下划线| int _employeeId;
String _name;
Customer _customer; |
| 常量(Constants)| 类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)| static final int MIN_WIDTH = 4;
static final int MAX_WIDTH = 999;
static final int GET_THE_CPU = 1; |

除非有充分理由，默认不应将实例或类变量声明为public。一般而言，在大多数情况下，默认情况下不需要显式地进行设置(set)和获取(gotten)，因为这些行为主要作为方法调用中的边缘效应(side effect)而产生。

一个合适的例子是：当类仅仅作为数据结构而无操作时。换句话说，在这种情况下，“使用struct而不是class（如果Java支持的话）时”，将类的实例变量声明为公有是一个合适的选择。

避免用一个对象访问一个类的静态变量和方法。应该用类名替代。例如：

在for循环中用作计数值的数字常量应避免直接赋值给代码。

避免在一个语句中给多个变量赋相同的值。它很难读懂。例如：

不要将赋值运算符用在容易与相等关系运算符混淆的地方。例如：

应该写成

避免使用内嵌赋值运算符旨在提升运行效率；这属于编译器处理职责的一部分。

应该写成

通常情况下，在涉及多种运算符的表达式中遵循圆括号以防止运算符优先顺序问题是个好方法。即使对于自己来说运算符优先级可能很明确，但对于他人来说未必。你不能假设其他程序员与您具有相同的认知水平关于运算符优先级。

设法让你的程序结构符合目的。例如：

应该代之以如下方法：

类似地：

应该写做：

当包含二元运算符的一个表达式位于三元运算符" ? : "中的"?"之前时，则需要为该表达式添加一组圆括号。

在注释中标识为(PENDING)，表示某些功能尚未实现但仍可正常运行的内容；同时用于标识假定存在但实际不存在的功能或逻辑缺陷。

以下实例阐述了规范布局一个包含单个公共类的Java源程序的方法。其相仿布局可参考相关技术资料中详细描述。

    <http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>

    <http://morningspace.51.net/>