Java注释详解

逃离我推掉我的手 2024-03-16 10:22 14阅读 0赞

## 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 维基百科][Javadoc]

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

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

#### 类的 Javadoc ####

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

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束。详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用 html 标签，如 ``、`<pre>`、`<a>`、`<ul>`、`` 等标签，通常详细描述都以段落 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）
 * 
 * 更长一些的描述可以写在这里。 （2）
 * 
 * 在 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 标签 ####

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

##### @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][http_www.51gjie.com_java_109.html]

#### 注释形式统一 ####

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

#### 注释的简洁 ####

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

#### 注释的一致性 ####

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

#### 注释的位置 ####

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

#### 注释的数量 ####

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

#### 删除无用注释 ####

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

#### 复杂的注释 ####

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

#### 多余的注释 ####

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

#### 必加的注释 ####

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

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

[Developer-Knowledge-Base]: https://github.com/zhongshuyi/developer-knowledge-base
[Javadoc]: https://zh.m.wikipedia.org/zh-cn/Javadoc
[http_www.51gjie.com_java_109.html]: http://www.51gjie.com/java/109.html