全国报名热线

15201841284

首页>Java>正文

强烈推荐,权威科学!Google出品的Java编程规范之四:编程实践和Javadoc

时间:2019-07-19 16:48:10   来源:上海尚学堂   阅读:

六、编程实践

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,这样更统一更友好。
分享:0