前言

好的代码规范是一个程序员的基本修炼，好的代码注释更能体现一个程序员的思维逻辑，虽然代码是用来给机器运行的，我们只要能写出能让编译器运行的代码就行了，但是如果没有好的编码规范，到项目后期，加入开发的人员逐渐增多时，每个人的编码风格都不一样，这就会让项目维护者很难维护，所以开始就要制定一些好的规范来让大家遵守，这样才能写出可维护，健壮的项目，这就是接下来要做的事情。

注释

注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
注释只是为了提高可读性，不会被计算机编译。换句话讲：代码是写给机器运行的，注释是写给人阅读的；

注释的意义

注释就是对代码的解释和说明。目的是为了让别人和自己很容易看懂，一看就知道这段代码是做什么用的。正确的程序注释一般包括序言性注释和功能性注释。序言性注释的主要内容包括模块的接口、数据的描述和模块的功能。模块的功能性注释的主要内容包括程序段的功能、语句的功能和数据的状态。

不同语言的注释

不同语音有不同的注释格式，如Java注释，c注释，HTML注释，Css注释，C++的注释；每个语言对注释的要求也不尽一样；

Java注释

注释的通用用法

  1. //  这是一个单行注释
  3. /*
  4.  * 这是
  5.  * 多行
  6.  * 注释
  7.  */
  9. /**
  10. *   这是javadoc注释
  11. */

注释分类

  1. 版权注释；
  2. 类注释(Class)；
  3. 构造函数注释(Constructor)；
  4. 方法注释(Methods)；
  5. 代码块注释(Block)；
  6. 单句注释；
  7. 字段名注释；

1、版权注释

版权注释主要用来声明公司的一些基本信息等:

  1. 1. /** 
  2. 2.  * projectName: xxx
  3. 3.  * fileName: Tk.java 
  4. 4.  * packageName: xxxx
  5. 5.  * date: 2017年12月18日下午12:28:39 
  6. 6.  * copyright(c) 2017-2020 xxx公司
  7. 7.  */

2、类注释(Class)

类注释(Class)主要用来声明该类用来做什么，以及创建者、创建日期版本、包名等一些信息:

1. /**
    * 这是用户类.
    * <p>更详细的描述
2.  * @version V1.0
3.  * @author fendo
8.  **/

3、构造函数注释(Constructor)

构造函数注释(Constructor)主要用来声明该类的构造函数、入参等信息:

1. **
2. * 构造函数.
3. * @param: [sid, pid]
4. */

4、方法注释(Methods)

方法注释(Methods)主要用来声明该类的作用、入参、返回值、异常等信息:

1. /**
   * 添加一个用户.
   * <p>更详细的描述
2. * @author  fendo
5. * @param:  xxxx
6. * @return: String
7. * @throws: 
8. */

5、代码块注释(Block)

1. /**
2.  * 实例化一个用户
3.  * xxxxxxx
4.  */
5. User user=new User();

6、单句注释

User user=new User();  //实例化一个用户

7、字段名注释

1. /**
2.  * 用户名
3.  */
4. public String name;

或者使用如下格式:

1. /**用户名**/
2. public String name;

Javadoc注释规范

Javadoc是Sun公司提供的一个技术，从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。

javadoc标签

标签 说明
@author 作者标识
@version 版本号
@return 对函数返回值的描述
@deprecated 标识过期API（为了保证兼容性，仍可用，但不推荐用）
@throws 构造函数或方法会抛出的异常
@exception 同@throws
@see 引用，查看相关的内容，如类，方法，变量等，必须顶头写
{@link 包.类#成员} 引用，同@see，但可写在任意位置
{@value} 对常量注释，如果其值包含在文档中，通过改标签引用常量的值
{@code}} {@code text}将文本标记为code，会被解析成text} ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@param 说明方法的参数
@inheritDoc 用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

javadoc注释规范

Java文档

// 注释一行
/ *    */ 注释若干行  
/**   ……*/  注释若干行，写入Javadoc文档

文档格式
写在类上的文档标注一般分为三段：

  • 第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束
  • 第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
  • 第三段：文档标注，用于标注作者，创建时间，参阅类等信息
  1. 生成文档是HTML格式。
  2. 换行
  3. 分段

    (写在段前）)

示例

/** 
* show 方法的简述.
*
* <p>show 方法的详细说明第一行<br> 
* show 方法的详细说明第二行 
* @param b true 表示显示，false 表示隐藏 
* @return 没有返回值 
*/ 
public void show(boolean b) {
    frame.show(b);
}

注释在IDEA上的应用

版权信息设置

File ->Settings ->Editor -> Copyrgiht -> copyright Profiles 中可以添加版权信息；

image.png

这样就可以在新建类和接口的时候自动的添加版权注释了；
在已经存在的java代码中可以在package的上一行右键或者Alt+Enter 调出Generate选择Copyright进行添加版权注释；

类和接口的代码注释配置

File ->Settings ->Editor->File and Code Templates -> Files -> Class
image.png
我们可以在里面添加我们想要的注释

/**
* @program: ${PROJECT_NAME}
*
* @description: ${description}
*
* @author: Mr.Wang
*
* @create: ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
**/

生成方法注释

最简单的做法就是在方法上面输入/**并回车就会生成对应的方法注释，当然也有更复杂的做法；

  1. 打开Preferences
  2. Editor -> Live Templates -> 点击右边加号为自己添加一个Templates Group -> 然后选中自己的Group再次点击加号添加Live Templates

Java注释和JavaDoc - 图3
Java注释和JavaDoc - 图4

然后设置自己喜欢的快捷键 在Abbreviation里面 记得在Applicable in 里面勾选,起码也要勾选class

Java注释和JavaDoc - 图5

然后在Edit variables里面添加参数和返回值的自动取值

Java注释和JavaDoc - 图6

然后再你的方法上面直接输入/ + 你设置的Abbreviation快捷键 + tab键就直接生成了 （我设置的是/+ a + tab）
效果图：

Java注释和JavaDoc - 图7

生成方法注解模板

/**<br />* $description$<br />* @Param $params$<br />* @return $returns$<br />* @Author Mr.Wang<br />* <br />*/<br />

注意，这个和类注解模板有点不一样，这个是用两个$$ ，这个的作用就是生成后光标直接跳到当前位置，这样也可以直接去输入description的内容了 对于 Live Templates只能说真的很强大，你平常用的sout ,psvm什么都是里面的，大家可以自行百度一下学习一下。

IDEA与Javadoc

预览已经存在的javadoc使用快捷键ctrl+q或者command+Q；
image.png
IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。
Java注释和JavaDoc - 图9Java注释和JavaDoc - 图10

需要注意的参数：

  • JavaDoc 的源代码对象的选择，一般以模块（Module）为主，必要时可以单独选择必要的 Java 源代码文件，不推荐以 PRoject 为 JavaDoc 生成的源范围。里面有一个 Locale 可选填项，表示的是需要生成
  • JavaDoc 以何种语言版本展示，根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英文或者是当前操作系统的语言，既然是国人，建议在此填写 zh_CN，这样生成的 JavaDoc 就是中文版本的，当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。
  • 还有一个“Other command line arguments:”可选填项，非常重要，是填写直接向 javadoc.exe 传递的参数内容。因为有一些重要的设置，只能通过直接参数形式向 javadoc.exe 传递。这里必须要填写如下参数：

-encoding UTF-8 -charset UTF-8 -windowtitle “你的文档在浏览器窗口标题栏显示的内容”
-link https://docs.[Oracle](http://www.knowsky.com/article.asp?typeid=171).com/javase/7/docs/api

  • 第一个参数 -encoding UTF-8 表示你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中文等非英语字符乱码；
  • 第二个参数 -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码，目前所有浏览器都支持 UTF-8，这样最具有通用性，支持中文非常好；
  • 第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时，浏览器窗口标题栏显示的文字内容；
  • 第四个参数 -link 很重要，它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用，是使用全限定名称还是带有超链接的短名称，举个例子，我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件，包括我们自己生成的 JavaDoc。
  • -html5 可以让你生成符合html5规范的javadoc文档

当然对于中文来说上面的只拥一个参数也可以：-encoding UTF-8
JavaDoc 生成完毕，即可在其根目录下找到 index.html 文件，打开它就可以看到我们自己的标准 JavaDoc API 文档啦。