Google出品的Java编码规范,强烈推荐,权威又科学( 五 )


4、最后将所有的单词连接起来得到一个标识符 。
示例:
Prose formCorrectIncorrect------------------------------------------------------------------"XML HTTP request"XmlHttpRequestXMLHTTPRequest"new customer ID"newCustomerIdnewCustomerID"inner stopwatch"innerStopwatchinnerStopWatch"supports IPv6 on iOS?"supportsIpv6OnIossupportsIPv6OnIOS"YouTube importer"YouTubeImporterYoutubeImporter*加星号处表示可以 , 但不推荐 。
Note:在英语中 , 某些带有连字符的单词形式不唯一 。 例如:”nonempty”和”non-empty”都是正确的 , 因此方法名 checkNonempty和 checkNonEmpty也都是正确的 。
编程实践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(); // goodaFoo.aStaticMethod(); // badsomethingThatYieldsAFoo().aStaticMethod(); // very bad6.4 Finalizers: 禁用极少会去重写 Object.finalize 。
Tip:不要使用finalize 。 如果你非要使用它 , 请先仔细阅读和理解Effective Java 第7条款:“Avoid Finalizers” , 然后不要使用它 。
Javadoc7.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. */【Google出品的Java编码规范,强烈推荐,权威又科学】基本格式总是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 , 这样更统一更友好 。