Java基础——注释

Java 注释

• 为什么要有注释呢？

假设一个程序员新进入一个项目组，接手一个已离职程序员未完成的软件模块功能，当他打开原程序员编写的代码时，其中一个方法（或函数）有上百行代码但没有任何注释，这样造成的结果是，新程序员要花费很长的时间去理解原程序员的业务逻辑和思路，可能还会出现理解错误的情况。怎么解决这个问题呢？就是给程序添加必要的注释。

• 什么是注释？

Java 程序中的注释是方便程序阅读而写的一些说明性的文字，这些文字不会被视为代码来编译和执行。通过注释提高 Java 源代码的可读性，使得 Java 程序条理清晰，易于理解。

Java 的注释有三种：单行注释、多行注释、文档注释。

//注释一行
/* ...... */ 注释若干行
/** ...... */ 注释若干行，并写入 javadoc 文档

下面介绍 Java 程序员编写注释的规范。

1. 注释要简单明了，例如：

String engName = "bridge";        //工程师用户名

2. 边写代码边注释，在修改代码的同时修改相应的注释，以保证注释与代码的一致性。有时会出现修改了代码，但没有修改注释的情况，尤其是在使用 javadoc 产生 Java 文档时，已经修改了程序，但没修改文档注释，产生的 Java 文档还是原注释内容，引起错误。

3. 保持注释与其对应的代码相邻，即注释的就近原则，通常放在该段代码的上方或者放在该行代码的右边（单行注释）。

4. 在必要的地方注释，注释量要适中。在实际的代码规范中，建议代码注释占程序代码的比例达到 20% 左右。

5. 全局变量要有较详细的注释，包括对其功能、取值范围、用哪些方法存取它以及存取时的注意事项等说明。

6. 源文件头部要有必要的注释信息，包括文件名，版本号，作者，生成日期，模块功能描述（如具体功能、主要算法、内部各部分之间的关系、该文件与其他文件的关系等），主要方法清单及本文件历史修改记录等。以下是源文件头部注释示例：

   /**
   * Copy Right Information           : lan-qiao
   * Project                          : blue-bridge
   * JDK version used                 : jdk1.8.101
   * Author                           : YQ
   * Version                          : 2.1.0,2020/5/20
   */
   

   7. 方法的前面要有必要的注释信息，包括方法名称，功能描述，输入、输出及返回值说明，抛出异常等。以下是方法注释示例。

/**
* Description :对方法进行描述
* @param Hashtable 参数描述1
* @param OrderBean 参数描述2
* @return String 返回值描述
* @exception IndexOutOfBoundsException 对方法可能抛出的异常进行描述
*/
public String checkout(HashTable cart,OrderBean orderBean) throws IndexOutOfBoundsException{
    // 省略具体内容
}

文档注释标签语法。

@author，位置：类，标明开发该类模块的作者
@version，位置：类，标明该类的版本。
@see，位置：类、属性、方法，说明相关主题。
@param，位置：方法，对方法中某参数的说明。
@return，位置：方法，对方法返回值的说明。
@exception，位置：方法，对方法可能抛出的异常进行说明。
如下程序是为 HelloWorld 增加注释后的完整程序：

如下程序是为 HelloWorld 增加注释后的完整程序：

/**
* Copy Right Information            : lan-qiao
* Project                          : blue-bridge
* JDK version used                 : jdk1.8.101
* Author                           : YQ
* Version                          : 2.1.0, 2020/5/1
*/
public class HelloWorld{
/**
* Description: 主函数，程序入口
* @param String[] args
* @return void
*/
public static void main(String[] args){
    System.out.println("HelloWorld!");    //输出HelloWorld!到控制台
    }
}

由于现在我们书写的代码量还较少，读者不清楚类、方法、参数等概念的含义，因此对于注释只需了解并尽量使用，待积累了一定的代码量后再回头来研究这部分内容。

代码注解

注解的原则

好的命名增加代码阅读性，代码的命名往往有严格的限制。而注解不同，程序员往往可以自由发挥，单并不意味着可以为所欲为之胡作非为。优雅的注解通常要满足三要素。

Nothing is strange 没有注解的代码对于阅读者非常不友好，哪怕代码写的在清除，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。

Less is more 从代码维护角度来讲，代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。

// 根据id获取信息【废话注解】getMessageById(id)

Advance with the time 注解应该随着代码的变动而改变，注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。

注解格式

注解大体上可以分为两种，一种是javadoc注解，另一种是简单注解。javadoc注解可以生成JavaAPI为外部用户提供有效的支持javadoc注解通常在使用IDEA，或者Eclipse等开发工具时都可以自动生成，也支持自定义的注解模板，仅需要对对应的字段进行解释。参与同一项目开发的同学，尽量设置成相同的注解模板。

包注解

包注解在工作中往往比较特殊，通过包注解可以快速知悉当前包下代码是用来实现哪些功能，强烈建议工作中加上，尤其是对于一些比较复杂的包，包注解一般在包的根目录下，名称统一为package-info.java。

/** 
* 落地也质量检测 
* 1. 用来解决什么问题 
* 对广告主投放的广告落地页进行性能检测，模拟不同的系统，如Android，IOS等; 模拟不同的网络：2G，3G，4G，wifi等 
* 2. 如何实现 
* 基于chrome浏览器，用chromedriver驱动浏览器，设置对应的网络，OS参数，获取到浏览器返回结果。 
* 注意：网络环境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常规速度，可以根据实际情况进行调整 
* @author cruder 
* @time 2019/12/7 20:3 下午 
*/
package cn.mycookies.landingpagecheck;

类注解

javadoc注解中，每个类都必须有注解

属性注解

在每个属性前面必须加上属性注释，通常有一下两种形式，至于怎么选择，你高兴就好，不过一个项目中要保持统一

方法注释

在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。

构造方法注释

在每个构造方法前面必须加上注释，注释模板如下：

注意事项

而简单注解往往是需要工程师字节定义，在使用注解时应该注意一下几点：

枚举类的各个属性值都要使用注解，枚举可以理解为是常量，通常不会发生改变，通常会被在多个地方引用，对枚举的修改和添加属性通常会带来很大的影响。

保持排版整洁，不要使用行尾注释；双斜杠和星号之后要用1个空格分隔。