Java中注释的规范&规则

目录

---

Ps：按每段后的——可返回目录

---

为什么写注释？

• 提高代码可读性；
• 使程序条理清晰；
• 方便后期代码维护；
• 方便程序员间的交流沟通；
• 生成帮助文档。

——

---

Java注释的方法有三种：

1. 单行注释：
   单行注释，以//开头，//后的内容都是注释，直到这一行的行尾结束。
2. 多行注释：
   以/*星号开头，以*/结束，可以有多行。可以使用多行注释作为行内注释，但多行注释不能嵌套使用。
3. Javadoc注释：
   以/**开头，以*/结束，如果有多行，每行通常以*开头
   文档注释允许把关于程序的信息嵌入到程序内部，开发者可以用Javadoc工具提取这些信息，并把它们放在HTML文件中，形成帮助文档（后期写项目时，可以生成项目的API）
   操作：/** + Enter

——

---

Java注释具体使用细节：

1. 类、类属性、类方法接口
   必须注释且使用Javadoc注释。需要标明，创建者，创建时间，版本，以及该类的作用。如下所示:

   package indi.mario.learn.demo;
   /*** @author: mario
   * @date: 19-07-08
   * @version: 1.0.0
   * @deion: 生成Jpg工具类
   */
   public class JpgUtils {}

   原因：
   在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释：在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

2. 方法
   所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做了什么事情，实现了什么功能。如下所示：

   /** * 生成Jpg文件
   * @param htmlContent 待生成Jpg的 html内容
   * @param file 生成Jpg文件地址
   * @see JpgUtils#getFontPath()
   * @return true 生成成功 false 生成失败
   */
   public static boolean generateJpg(String htmlContent,File file){ … return result; }

   说明：对子类的实现要求或者调用的注意事项，请一并说明。
   方法内部单行注释，，在被注释语句上方另起一行，使用//注释。方法内容多行注释使用/* */注释，注意与代码对齐。

3. 常量
   对常量，我们需要使用多行注释，进行标明该常量的用途，如下所示:

   /*** @author: mario
   * @date: 19-07-08
   * @version: 0.0.1
   * @deion:
   */public class StatusConsts {
       /**
       * 博客地址
       */
       public static final String BLOG=“https://blog.csdn.net/InjoyMario”;
   }

4. 关键算法
   在关键算法上，添加注释并且按照顺序依次标明，写明白该方法为什么这么做。如下所示:

   /** * 应用场景:
   * 1. 在windows下,使用Thread.currentThread()获取路径时,出现空对象，导致不能使用
   * 2. 在linux下,使用JpgUtils.class获取路径为null,
   * 获取字体路径
   * @return 返回字体路径
   */
   private static String getFontPath(){
           String path="";
   // 1. ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
   URL url = (classLoader==null)?null:classLoader.getResource("/");
   String threadCurrentPath = (url==null)?"":url.getPath();
   // 2. 如果线程获取为null,则使用当前JpgUtils.class加载路径 if(threadCurrentPath==null||"".equals(threadCurrentPath)){
        path = JpgUtils.class.getClass().getResource("/").getPath();
   }
   // 3. 拼接字体路径
   StringBuffer stringBuffer = new StringBuffer(path); stringBuffer.append("/fonts/SIMKAI.TTF"); path = stringBuffer.toString(); return path;
   }

——

---

添加注释时的一点建议

1. 类中，接口等必须有创建时间、创建人、版本号、描述等注释。
2. 注释不是越多越好，比如：get/set方法就不需要写注释。更不需要每一行都写注释。
3. 注释需要写的简明易懂。特别是方法的参数，以及返回值。
4. 每一次修改时，相应的注释也应进行同步更新。
5. 在类，接口，方法中，应该都使用/** */Javadoc注释。因为这样调用者就不需要进入方法内部才知道方法的用处。提高编码效率。
6. 方法代码中如果有顺序之分，最好将代码也加上序号，如1，2，3等。
7. 所有的枚举类型字段都必须添加注释，说明每个数据项的用途。
8. 与其用半吊子英文解释，有的时候不如用中文注释说明清楚。
9. 代码如果修改时，注释也要相应修改，尤其是参数、返回值、异常、核心逻辑等的修改。
10. 谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果不用，则删除。
11. 如果注释包含多段内容，段与段之间需要用

    分隔，空行是没用的

12. 为了避免一行过长影响阅读效果，务必将每行的长度限制在80个字符以内.
13. 使用 关键字 来强调关键字，建议强调的内容有：java关键字、包名、类名、方法名、接口名、字段名、参数名
14. 注释要求有二：1.要能反映设计思想和代码逻辑；2.能够描述业务含义
15. 好的命名、代码结构是自解释的。
16. 英文注释避免拉丁风格的缩写。比如使用also knwon as而不是aka， 使用that is或to be specific而不是i.e.，使用for example而不是e.g.，使用in other words或namely而不是viz.
17. 特殊注释标记：清注明标记人和标记时间。注意及时处理这些标记，通过标记扫描，经常清理这些标记。线上故障有时候就源于这些标记：
    （1）待办事宜（TODO）：（标记人，标记时间，[预计处理时间]）
    表示需要实现，但目前还没有实现的功能。这实际上是一个Javadoc的标签。目前Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为他是一个Javadoc标签）
    （2）错误，不能工作（FIXME）：（标记人，标记时间，[预计处理时间]）
    在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

——

---

Javadoc注释标签语法：

标签	作用域	说明
@author	文件、类、属性、方法	标明开发该类模块的作者，多个作者使用多个@author标签标识，java doc中显示按输入时间顺序罗列。
@version	文件、类、方法	标识注释对象的版本号
@see	类，属性，方法	参考转向（相关主题）
@param	方法	对方法中某参数的说明
@return	方法	对方法返回值的说明
@exception	方法	方法抛出的异常类型
@throws	方法	方法抛出的异常类型说明
@deprecated	文件、类、方法	说明对象过期，应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API
@link	类、方法	链接到一个目标，用法类似@see，区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。例如{@link …}
@since JDK版本	文件、类	用于标识编译该文件所需要的JDK环境。

Java注释的使用顺序

• @author (classes and interfaces only, required)
• @version (classes and interfaces only, required. See footnote 1)
• @param (methods and constructors only)
• @return (methods only)
• @exception (@throws is a synonym added in Javadoc 1.2)
• @see
• @since
• @serial (or @serialField or @serialData)
• @deprecated (see How and When To Deprecate APIs)

1. 多个@author标记，应该按照时间顺序排列，即原作者应该排在第一个位置
2. 多个@param标记，应该按照参数定义的顺序排列
3. 多个@exception（或是@thrown）应该按照异常的字母顺序排列
4. 多个@see标记，应该按照注释的逻辑顺序排列，即从最近的到最远的，从最具体的到最一般的

特别声明：

1. Javadoc针对public类生成注释文档
2. 标记部分跟在描述部分之后，且前面必须有一个空行间隔
3. Javadoc只能在public、protected修饰的方法或者属性之上
4. 如果方法有参数，@param必须包含，而且每个对应一个参数
   如果方法有返回值，@return必须包含
5. Javadoc注释的格式化：前导*号和HTML标签
6. Javadoc注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。
7. 如果源文件中有用到@version,@author标记，则在执行Javadoc命令时，要加-version -author
javadoc -version -author -d doc *.java
   （其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）
8. 文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。

——

---

@see:
    注释中，为更好描述，需要引用和参考其他代码，为更好阅读体验，Javadoc支持链接跳转，需要用到@see
    完整的用法：
         @see package.class#member
    具体用法：

1. 如果指向在当前类中，可以只写#号后面的
2. 如果指向在当前包中，可以省略包名
3. 如果指向在当前项目其它包中，需要指向全路径

@link与@see的小区别：
@see必须顶头写，而@link可以随意放，否则@see会失去效用。
——

---

注释的抽取

假设HTML文件将被存放在目录docDirectory下。执行以下步骤：

切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录(如果存在overview.html文件的话，这也是它所在目录)。
如果是一个包，应该运行命令：

javadoc -d docDirectory nameOfPackage

或对于多个包生成文档，则运行：

javadoc -d docDirectory nameOfPackage1 nameOfpackage2...

如果文件在默认包中，就应该运行：

javadoc -d docDirectory *.java

可以使用-link，用来为标准类添加超链接。例如：

javadoc -link http://docs.oracle.com/javase/8/docs/api *.java

那么，所有的标准类库类都会自动的链接到Oracle网站的文档。、
（这里参考了故克里的博文：Javadoc注释的生成规则）
——

---

参考文档

官方文档：http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html

本文作者： InjoyMario
本文链接： https://blog.csdn.net/InjoyMario/article/details/95043728
版权声明： 本博客所有文章除特别声明外，均采用 ©BY-NC-SA 许可协议。转载请注明出处！