注释
- [1. 单行注释](#1. 单行注释)
- [2. 多行注释](#2. 多行注释)
- [3. 文档注释](#3. 文档注释)
1. 单行注释
使用方法
单行注释以 //
开头,注释内容从 //
开始到行尾结束。它们通常用于对单行代码进行简短说明,或者在代码中插入临时注释。
示例
java
int x = 10; // 定义变量x并赋值为10
// 打印变量x的值
System.out.println(x);
最佳实践
- 使用单行注释来解释复杂或不易理解的代码行。
- 避免冗长的单行注释,保持简洁明了。
- 在代码块前使用单行注释来描述该块的功能。
2. 多行注释
使用方法
多行注释以 /*
开头,以 */
结束,可以跨越多行。多行注释适用于对较长的代码块进行详细说明,或者用于注释掉大段代码。
示例
java
/*
这个方法用于计算两个数的和
参数:a - 第一个整数
b - 第二个整数
返回值:两个整数的和
*/
public int add(int a, int b) {
return a + b;
}
/*
这是一个示例,演示如何注释掉大段代码
public void exampleMethod() {
// 这里的代码被注释掉了
}
*/
最佳实践
- 使用多行注释对函数、类或复杂的逻辑进行详细解释。
- 避免嵌套多行注释,这会导致代码难以维护。
- 当临时禁用代码段时,可以使用多行注释,但应尽快移除不再需要的注释代码。
3. 文档注释
使用方法
文档注释以 /**
开头,以 */
结束,通常用于类、接口、方法和字段的声明前。Javadoc工具可以解析这些注释并生成HTML格式的API文档。
常用标签
@param
用于描述方法的参数。@return
用于描述方法的返回值。@throws
或@exception
用于描述方法可能抛出的异常。@see
用于提供相关信息的链接。@since
表示该元素从哪个版本开始存在。@deprecated
标识不推荐使用的元素,并提供替代信息。
示例
java
/**
* 这个类表示一个简单的计算器
*
* @since 1.0
*/
public class Calculator {
/**
* 计算两个整数的和
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的和
* @since 1.0
*/
public int add(int a, int b) {
return a + b;
}
/**
* 计算两个整数的差
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的差
* @since 1.0
*/
public int subtract(int a, int b) {
return a - b;
}
/**
* 计算两个整数的乘积
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的乘积
* @throws IllegalArgumentException 如果参数为负数
* @since 1.1
*/
public int multiply(int a, int b) {
if (a < 0 || b < 0) {
throw new IllegalArgumentException("参数不能为负数");
}
return a * b;
}
}
最佳实践
- 使用文档注释为公共API提供详细说明,这有助于自动生成开发文档。
- 描述清楚方法的输入输出和异常情况,以便使用者了解方法的使用方法和注意事项。
- 保持文档注释简洁且有意义,避免冗长和无关的信息。