如需复制、传播，请附上本声明，谢谢。
原文出处：http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html，
译文出处：http://morningspace.51.net/，[email protected]
（续）
5 注释(Comments)
Java程序有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的，使用/*...*/和//界定的注释。文档注释(被称为"doc comments")是Java独有的，并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。
实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。
注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。
在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的的注释很容易过时。通常应避免那些代码更新就可能过时的注释。
注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。
注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。
5.1 实现注释的格式(Implementation Comment Formats)
程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。
5.1.1 块注释(Block Comments)
块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。
块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：
/* * 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)作让步。
参见"文档注释"
5.1.2 单行注释(Single-Line Comments)
短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：
if (condition) { /* Handle the condition. */ ... }
5.1.3 尾端注释(Trailing Comments)
极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。
以下是一个Java代码中尾端注释的例子：
if (a == 2) { return TRUE; /* special case */ } else { return isPrime(a); /* works only for odd a */ }
5.1.4 行末注释(End-Of-Line Comments)
注释界定符"//"，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子：
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 文档注释(Documentation Comments)
注意：此处描述的注释格式之范例，参见"Java源文件范例"
若想了解更多，参见"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)。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前：
/** * The Example class provides ... */ public class Example { ...
注意顶层(top-level)的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。
若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。
文档注释不能放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。
6 声明(Declarations)
6.1 每行声明变量的数量(Number Per Line)
推荐一行一个声明，因为这样以利于写注释。亦即，
int level; // indentation level int size; // size of table
要优于，
int level, size;
不要将不同类型变量的声明放在同一行，例如：
int foo, fooarray[]; //WRONG!
注意：上面的例子中，在类型和标识符之间放了一个空格，另一种被允许的替代方式是使用制表符：
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 ... } }
该规则的一个例外是for循环的索引变量
for (int i = 0; i < maxLoops; i++) { ... }
避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名：
int count; ... myMethod() { if (condition) { int count = 0; // AVOID! ... } ... }
6.4 类和接口的声明(Class and Interface Declarations)
当编写类和接口是，应该遵守以下格式规则：
- 在方法名与其参数列表之前的左括号"("间不要有空格
- 左大括号"{"位于声明语句同行的末尾
- 右大括号"}"另起一行，与相应的声明语句对齐，除非是一个空语句，"}"应紧跟在"{"之后
class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... } - 方法与方法之间以空行分隔
7 语句(Statements)
7.1 简单语句(Simple Statements)
每行至多包含一条语句，例如：
argv++; // Correct argc--; // Correct argv++; argc--; // AVOID!
7.2 复合语句(Compound Statements)
复合语句是包含在大括号中的语句序列，形如"{ 语句 }"。例如下面各段。
- 被括其中的语句应该较之复合语句缩进一个层次
- 左大括号"{"应位于复合语句起始行的行尾；右大括号"}"应另起一行并与复合语句首行对齐。
- 大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else或for控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug。
7.3 返回语句(return Statements)
一个带返回值的return语句不使用小括号"()"，除非它们以某种方式使返回值更为显见。例如：
return; return myDisk.size(); return (size ? size : defaultSize);
7.4 if，if-else，if else-if else语句(if, if-else, if else-if else Statements)
if-else语句应该具有如下格式：
if (condition) { statements; } if (condition) { statements; } else { statements; } if (condition) { statements; } else if (condition) { statements; } else{ statements; }
注意：if语句总是用"{"和"}"括起来，避免使用如下容易引起错误的格式：
if (condition) //AVOID! THIS OMITS THE BRACES {}! statement;
7.5 for语句(for Statements)
一个for语句应该具有如下格式：
for (initialization; condition; update) { statements; }
一个空的for语句(所有工作都在初始化，条件判断，更新子句中完成）应该具有如下格式：
for (initialization; condition; update);
当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。
7.6 while语句(while Statements)
一个while语句应该具有如下格式
while (condition) { statements; }
一个空的while语句应该具有如下格式：
while (condition);
7.7 do-while语句(do-while Statements)
一个do-while语句应该具有如下格式：
do { statements; } while (condition);
7.8 switch语句(switch Statements)
一个switch语句应该具有如下格式：
switch (condition) { case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; }
每当一个case顺着往下执行时(因为没有break语句)，通常应在break语句的位置添加注释。上面的示例代码中就包含注释/* falls through */。
7.9 try-catch语句(try-catch Statements)
一个try-catch语句应该具有如下格式：
try { statements; } catch (ExceptionClass e) { statements; }
一个try-catch语句后面也可能跟着一个finally语句，不论try代码块是否顺利执行完，它都会被执行。
try { statements; } catch (ExceptionClass e) { statements; } finally { statements; }
本文地址：http://com.8s8s.com/it/it17987.htm