强烈推荐，权威科学！Google出品的Java编程规范之四：编程实践和Javadoc

六、编程实践

6.1 @Override：能用则用

只要是合法的，就把 @Override注解给用上。

6.2 捕获的异常：不能忽视

除了下面的例子，对捕获的异常不做响应是极少正确的。(典型的响应方式是打印日志，或者如果它被认为是不可能的，则把它当作一个 AssertionError重新抛出。)
如果它确实是不需要在catch块中做任何响应，需要做注释加以说明(如下面的例子)。
 
try {
 
  int i = Integer.parseInt(response);
 
  return handleNumericResponse(i);
 
} catch (NumberFormatException ok) {
 
  // it's not numeric; that's fine, just continue
 
}
 
return handleTextResponse(response);

 
例外：在测试中，如果一个捕获的异常被命名为 expected，则它可以被不加注释地忽略。下面是一种非常常见的情形，用以确保所测试的方法会抛出一个期望中的异常， 因此在这里就没有必要加注释。

 
try {
 
  emptyStack.pop();
 
  fail();
 
} catch (NoSuchElementException expected) {
 
}
 

6.3 静态成员：使用类进行调用

使用类名调用静态的类成员，而不是具体某个对象或表达式。
 
Foo aFoo = ...;
 
Foo.aStaticMethod(); // good
 
aFoo.aStaticMethod(); // bad
 
somethingThatYieldsAFoo().aStaticMethod(); // very bad

 

6.4 Finalizers: 禁用

极少会去重写 Object.finalize。
Tip：不要使用finalize。如果你非要使用它，请先仔细阅读和理解Effective Java 第7条款：“Avoid Finalizers”，然后不要使用它。

七、Javadoc

7.1 格式

7.1.1 一般形式
Javadoc块的基本格式如下所示：
 
/**
 
 * Multiple lines of Javadoc text are written here,
 
 * wrapped normally...
 
 */
 
public int method(String p1) { ... }
 
或者是以下单行形式：
 
/** An especially short bit of Javadoc. */
 
基本格式总是OK的。当整个Javadoc块能容纳于一行时(且没有Javadoc标记@XXX)，可以使用单行形式。

7.1.2 段落
空行(即，只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。除了第一个段落，每个段落第一个单词前都有标签

，并且它和第一个单词间没有空格。

7.1.3 Javadoc标记
标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。当描述无法在一行中容纳，连续行需要至少再缩进4个空格。
 

7.2 摘要片段

每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中。

这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。它不会以 A{@codeFoo}isa...或 Thismethod returns...开头, 它也不会是一个完整的祈使句，如 Savethe record...。然而，由于开头大写及被加了标点，它看起来就像是个完整的句子。

Tip：一个常见的错误是把简单的Javadoc写成 /** @return the customer ID */，这是不正确的。它应该写成 /** Returns the customer ID. */。

7.3 哪里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：

7.3.1 例外：不言自明的方法
对于简单明显的方法如 getFoo，Javadoc是可选的(即，是可以不写的)。这种情况下除了写“Returns the foo”，确实也没有什么值得写了。
单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。
Tip：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名 getCanonicalName， 就不应该忽视文档说明，因为读者很可能不知道词语 canonical name指的是什么。

7.3.2 例外：重写
如果一个方法重写了超类中的方法，那么Javadoc并非必需的。

7.3.3 可选的Javadoc
对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为， 那么这个注释应该写成Javadoc，这样更统一更友好。