Java注释详解

Java 注释

此文章已收录至项目 Developer-Knowledge-Base

有三种注释：单行注释，多行注释与文档注释

1. 单行注释 //，最常用的注释其注释内容从 // 开始到本行结尾。
2. 多行注释 从 /* 开始直至第一个 */ 出现都属于多行注释，但多行注释不能嵌套，多行注释也可以注释掉不需要的代码
3. 文档注释 可以自动地生成文档，这种注释以 /** 开始，以 */ 结束

/**
 * 这就是传说中的文档注释
 * @author 作者
 * 可以自动生成文档
 */

public class Hello{
 public static void main(String[] args){
        //这是单行注释
  System.out.println("你好");
 /*
        System.out.println("你好");
  System.out.println("你好");
  这里都是多行注释
 */
 }
}

文档注释

Javadoc 维基百科

Java 文档注释可以用来自动地生成文档。在 JDK 中有个 javadoc 的工具，可以由源文件生成一个 HTML 文档。使用这种方式注释源文件的内容，显得很专业，并且可以随着源文件的保存而保存起来。也就是说，当修改源文件时，也可能对这个源代码的需求等一些注释性的文字进行修改，那么，这时候可以将源代码和文档一同保存，而不用再另外创建一个文档。

Javadoc 的第一行是类或方法的简短描述，之后是详细描述，因为所有的 Javadoc 都被视为 HTML，所以可以多个段落可以用 <p> 标签

类的 Javadoc

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束。详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用 html 标签，如 <p>、<pre>、<a>、<ul>、<i> 等标签，通常详细描述都以段落 p 标签开始。详细描述和概要描述中间通常有一个空行来分割

第三段：文档标注，用于标注作者、创建时间、参阅类等信息，还有泛型信息

// import statements

/**
 *  简短的说明。
 *  详细的说明
 * @author     姓名  <address @ example.com>
 * @version    1.6（程序的当前版本号）
 * @since       1.2（加入该类时程序的版本号）
 */
public class Test {
    // class body
}

方法的 Javadoc

写在方法上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束

第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束

第三段：文档标注，用于标注参数、返回值、异常、参阅等

方法详细描述上经常使用 html 标签来，通常都以 p 标签开始，而且 p 标签通常都是单标签，不使用结束标签，其中使用最多的就是 p 标签和 pre 标签，ul 标签，i 标签。

pre 元素可定义预格式化的文本。被包围在 pre 元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre 标签的一个常见应用就是用来表示计算机的源代码。

一般 p 经常结合 pre 使用，或者 pre 结合@code 共同使用 (推荐@code 方式)
一般经常使用 pre 来举例如何使用方法

/**
 * 简短的单行描述。                                         （1）
 * <p>
 * 更长一些的描述可以写在这里。                              （2）
 * </p>
 * 在 HTML 段落分隔的连续段落中还可以有更多注释。
 *
 * @param  variable 描述文本。                              （3）
 * @return  描述文本。
 */
public int methodName (...) {
    // method body with a return statement
}

    /**
     * 求和。
     *
     * @param parameter1 参数 1
     * @param parameter2 参数 2
     * @return 两数和
     */
    public int sum(int parameter1, int parameter2) {
        return parameter1 + parameter2;
    }

变量的 Javadoc 注释

与方法类似的注释也可以用于变量的注释，只包含了对变量的简短描述

/**
 * 对变量的描述。
 */
private int debug = 0;

所有 Javadoc 标签

标签&参数	用途	适用于	引入版本
@author John Smith	描述作者。可以是作者的名字也可以是指向作者的 a 标签等	类、接口、枚举
{@docRoot}	表示从任何生成的页面生成的文档的根目录的相对路径。	类、接口、枚举、成员、方法
@version 版本	提供软件版本，每个类或接口最多一个。	类、接口、枚举
@since 起始	描述此功能首次存在的时间或者版本号。	类、接口、枚举、成员、方法
@see 参考	提供指向其他文档元素的链接。一般用于标记该类相关联的类	类、接口、枚举、成员、方法
@param 名称 描述	描述方法的一个参数。	方法
@return 描述	描述返回值。	方法
@exception 类 描述 `` @throws 类 描述	描述可能从此方法抛出的异常。	方法
@deprecated 描述	描述一个过时的方法。	类、接口、枚举、成员、方法
{@inheritDoc}	从被覆盖的方法复制描述。	覆盖方法	1.4.0
{@link 参考}	用于快速链接到相关代码	类、接口、枚举、成员、方法
{@linkplain 参考}	与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。	类、接口、枚举、成员、方法
{@value #STATIC_FIELD}	返回静态成员的值。	静态成员	1.4.0
{@code 文本}	在代码字体中格式化文字文本，等同于<code> {@literal} </code>。	类、接口、枚举、成员、方法	1.5.0
{@literal 文本}	表示文本，随附的文本被解释为不包含 HTML 标记或嵌套的 javadoc 标记。	类、接口、枚举、成员、方法	1.5.0
{@serial 文本}	在 Javadoc 注释中用于默认的可序列化字段。	成员
{@serialData 文本}	记录 writeObject() 或 writeExternal() 方法写入的数据。	成员、方法
{@serialField 文本}	记录 ObjectStreamField 组件。	成员

@link

@link 的使用语法 {@link 包名.类名#方法名(参数类型)}，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名。方法名，使用此文档标记的类或者方法，可用通过按住 Ctrl 键 + 单击 可以快速跳到相应的类或者方法上

示例

// 完全限定的类名
{@link java.lang.Character}

// 省略包名
{@link String}

// 省略类名，表示指向当前的某个方法
{@link #length()}

// 指定参数及参数类型
{@link java.lang.String#charAt(int)}

@code

{@code text} 会被解析成 <code> text </code>

将文本标记为代码样式的文本，在 code 内部可以使用 < 、> 等不会被解释成 html 标签，code 标签有自己的样式

一般在 Javadoc 中只要涉及到类名或者方法名，都需要使用@code 进行标记。

@param

一般类中支持泛型时会通过@param 来解释泛型的类型

/**
* @param <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}

在方法上使用时后面跟参数名，再跟参数描述

/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

@return

描述返回值信息

/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}

@throws

跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常

/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}

@see

既可以用来类上也可以用在方法上，表示可以参考的类或者方法

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

@value

用于标注在常量上，{@value} 用于表示常量的值

/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

注释的规范

原文：http://www.51gjie.com/java/109.html

注释形式统一

在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。

注释的简洁

内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。

注释的一致性

在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。

注释的位置

保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。

注释的数量

注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到 20% 左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。

删除无用注释

在代码交付或部署发布之前，必须删掉临时的或无关的注释，以避免在日后的维护工作中产生混乱。

复杂的注释

如果需要用注释来解释复杂的代码，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单便于使用而牺牲性能，但必须保持性能和可维护性之间的平衡。

多余的注释

描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现。

必加的注释

典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中添加注释。为了防止问题反复出现，对错误修复和解决方法的代码使用注释，尤其是在团队环境中。

注释在编译代码时会被忽略，不编译到最后的可执行文件中，所以注释不会增加可执行文件的大小。