黑马程序员技术交流社区

标题: JAVA基础规范（三）注释规范 [打印本页]

---

作者: 神兽    时间: 2015-7-25 14:53
标题: JAVA基础规范（三）注释规范

2.1 注释类型

2.1.1 JavaDoc注释

略。

2.1.2 失效代码注释

  由/*...*/界定，标准的C-Style的注释。专用于注释已失效的代码。

/*

* Comment out the code

* String s = "hello";

* System.out.println(s);

*/

2.1.3 代码细节注释

  由//界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注释的失效代码分开

  除了私有变量外，不推荐使用行末注释。

class MyClass {

private int myField; // An end-line comment.

public void myMethod {

//a very very long

//comment.

if (condition1) {

//condition1 comment

...

} else{

//elses condition comment

...

}

}

}

2.2 注释的格式

    注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。

    为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。

    Class必须以@author 作者名声明作者，不需要声明 (version与)date，由版本管理系统保留此信息。(II)

    如果注释中有超过一个段落，用<p>分隔。(II)

    示例代码以<pre></pre>包裹。(II)

    标识(java keyword, class/method/field/argument名，Constants)以<code></code>包裹。(II)

    标识在第一次出现时以

{@linkxxx.Myclass}

注解以便JavaDoc与IDE中可以链接。(II)

2.3 注释的内容

2.3.1 可精简的注释内容

    注释中的每一个单词都要有其不可缺少的意义，注释里不写"@param name -名字"这样的废话。
    如果该注释是废话，连同标签删掉它，而不是自动生成一堆空的标签，如空的@param name，空的@return。

2.3.2 推荐的注释内容

    对于API函数如果存在契约，必须写明它的前置条件(precondition)，后置条件(postcondition)，及不变式(invariant)。(II)

    对于调用复杂的API尽量提供代码示例。(II)

    对于已知的Bug需要声明。(II)

    在本函数中抛出的unchecked exception尽量用@throws说明。(II)

2.3.3 Null规约

   如果方法允许Null作为参数，或者允许返回值为Null，必须在JavaDoc中说明。
   如果没有说明，方法的调用者不允许使用Null作为参数，并认为返回值是Null Safe的。

/**

* 获取对象.

* @ return the object to found or null if not found.

*/

Object get(Integerid)

{   ...  }

2.3.4 特殊代码注释

    代码质量不好但能正常运行，或者还没有实现的代码用//TODO: 或 //XXX:声明

    存在错误隐患的代码用//FIXME:声明

---

作者: 徐会会    时间: 2015-7-25 17:27
学习一下。。。

---

欢迎光临 黑马程序员技术交流社区 (http://bbs.itheima.com/)

黑马程序员IT技术论坛 X3.2