章
目
录
我们在新建一个类的时候经常忘了写或懒得写Javadoc相关注释，这不利于我们代码的可读性，也会极大增加项目的维护成本，于是可以利用Intellij IDEA工具，进行自动生成标准的模板注释，方便后期维护，而且还可以一键生成整个JavaDoc文档。下面潘老师来带大家演示下该如何实现。
1、配置模板
我们打开：File -> Settings ，弹出”Setting对话框”
2、找到 File -> Settings -> Editor -> File and Code Templates -> Includes，编辑FileHeader模板如下：
/**
* <h3>${PROJECT_NAME}</h3>
* @description
* <p>${description}</p>
* @author panziye
* @date ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
**/
具体说明如图：
3、我们在TestDemo1项目中新建Class（我在此将类命名为TestDoc，放在包）会发现多了一步输入描述：
4、创建成功后，其结构如下（我加了main方法）：
2、一键生成JavaDoc
1、打开Tools -> Generate JavaDoc配置如下：
-tag date:a:日期 -tag description:a:描述 -encoding UTF-8 -charset UTF-8
2、生成后文档如下：
3、双击index.html浏览器打开
（忽略包名，格式写错了）
点开类：
3、JavaDoc插件
其实我们还可以使用JavaDoc插件帮助我们有效地管理JavaDoc文档，应该支持到对应得方法、形参、返回值等等注解模板的自动生成，不过我这里由于IDEA版本太低，安装失败，有兴趣的可以去Settings -> Plugins中安装使用，在此不再赘述。
4、补充说明
阿里巴巴Java开发手册之注释规约：
类，类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用//XX方式。
所有的抽象方法（包括接口中的方法）必须要用Javadoc注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
所有的类都必须添加创建者和创建日期。
方法内部的单行注释，在被注释语句上方另起一行，使用//注释。方法内部的多行注释，使用/* */注释，注意与代码对齐。
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
与其用不熟练的英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
在修改代码的同时，要对注释进行相应的修改，尤其是参数，返回值，异常，核心逻辑等的修改。
谨慎注释掉代码。要在上方详细说明，而不是简单的注释掉。如果无用，则删除。
对于注释的要求：
（1）能够准确反映设计思想和代码逻辑。
（2）能够描述业务含义，使其他程序员能够迅速了解代码背后的信息。完全没有注释的大段代码对于阅读者形同天书；注释是给自己看的，应做到即使间隔很长时间，也能清晰理解当时的思路，注释也是给继任者看的，使其能够快速接替自己的工作。
好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，因为代码的逻辑一旦修改，修改注释是相当大的负担。
特殊注释标记，请标明标记人与标记时间。注意及时处理这些标记，通过标记扫描经常处理此类标记。有时候线上故障就来源于这些标记处的代码。
