Java注释规范简介说明

转自:http://www.java265.com/JavaCourse/202111/1725.html

下文笔者讲述java中注释规范的相关说明，如下所示:

注释形式统一

在整个团队中，我们应该遵循同一种注释规范，可通过设置注释模板的方式，使用java注释变得规范

注释的简洁

通过注释，可直接得到下面代码的功能，为程序后续维护提供便利

注释的一致性

在编写代码之前或同步进行代码注释的编写
修改代码时，也同时修改注释

注释的位置

使代码同注释相邻，避免出现代码和注释无法对应，长年累月后都不知道注释所对应的代码

注释的数量

整个代码中，注释不宜过多，但也不能太少

删除无用注释

删除注释中的临时内容及无用的注释信息，避免后续维护时，给人误导行为

复杂的注释

避免编写令人难以理解的注释

多余的注释

当有些代码非常清晰时，我们应该避免加入一些无关紧要的注释信息

必加的注释

如：一些实现子类中，算法中，我们如果不加入注释，则让后人无法理解相应的代码

注释不会增加文件的大小

Java中的注释文件不会增加文件的大小

---

java注释示例

---

文件头注释

文件头注释以/*开始，以*/结束，需要注明该文件的创建时间、文件名、命名空间信息
如：

/* Created on 2021-11-16
     * File User.java
     * Package com.Java265.other
     * Create Date:2021-11-16
     */

类、接口注释

类、接口的注释采用/**...*/
描述部分用来书写该类的作用或者相关信息，块标记部分必须注明作者个版本
例：

/** Title：XXXX OCR
     * Description:XXXX OCR 3.0
     * Copyright:Copyright(c) 2021
     * Company:XXXX 有限公司
     * 
     * @author Adeal
     * @version 3.0
     */ 

构造函数注释

构造函数注释采用/**...*/
描述部分注明构造函数的作用

 
 /**
     * 默认构造函数
     */
带块标记的示例如下：

/**
     * 带参数构造函数，初始化模式名、变量名称和数据源类型
     * @param schema
     * Ref 模式名
     * @param name
     * Ref 变量名称
     * @param type
     * by Val 数据源类型
     */

域注释

域注释可以出现在注释文档里面
也可以不出现在注释文档里面
用/**...*/的域注释将会被认为是注释文档而出现在最终生成的HTML报告里面（Javadoc）
而使用/*...*/的注释则会被忽略掉
如：

/**
     * @作者 XXX
     * @创建时间 Jan 16,2021 05:05:11 AM
     */

方法注释

方法注释采用/**...*/
描述部分注明方法的功能
块标记部分注明方法的参数
返回值，异常信息
如:

/**
     * 求最大公约数
     *
     * @param int a
     *  a:待求公约数的参数
     */