转自: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
*/
方法注释
方法注释采用/**...*/
描述部分注明方法的功能
块标记部分注明方法的参数
返回值,异常信息
如:
/**标签:...,Java,简介,代码,param,注释,java,构造函数 From: https://blog.51cto.com/u_15736642/5787191
* 求最大公约数
*
* @param int a
* a:待求公约数的参数
*/