当编写代码很少,没有几行的时候我们可以很容易知道代码的含义。但是随着代码行数的增加,逻辑复杂性的增加就不容易看出代码的含义了,就需要我们逐行阅读分析。
1.注释是什么?
注释就是一种特殊的代码
它是起到提示作用的,和具体的逻辑没有任何关系。在编写代码时,使用注释去说明代码逻辑,良好的注释是代码可读性和可维护性的关键。
2.注释的种类
1)单行注释
单行注释以 //
开始,可以在一行代码的末尾添加注释
// 这是一个单行注释
int x = 9; // 初始化变量 x
2)多行注释
多行注释以 /*
开始,以 */
结束,可以跨越多行
/*
* 这是一个多行注释
* 可以包含多行文字
*/
int x = 10;
3)文档注释
文档注释以 /**
开始,以 */
结束,用于生成API文档。通常用于类、方法、字段的说明
/**
* 这是一个文档注释
*/
public class Test {
/**
* 这是一个文档注释
* @param num1 数1
* @param num2 数2
* @return 传入两个数的和
*/
public int sum(int num1, int num2) {
return num1 + num2;
}
}
3. 注释标签
注释标签主要用于编写 文档注释(Javadoc)
,以生成API文档。
以下是常用的文档注释标签:
@param
:
用于描述方法的参数
/**
* 计算两个数的和
* @param a 第一个数
* @param b 第二个数
* @return 两个数的和
*/
public int add(int a, int b) {
return a + b;
}
@return
用于描述方法的返回值
/**
* 获取姓名
* @return 姓名字符串
*/
public String getName() {
return name;
}
**@throws
**
@exception
@throws 和 @exception 用于描述方法可能抛出的异常
/**
* 读取文件内容
* @param filePath 文件路径
* @throws IOException 如果读取文件时发生I/O异常
*/
public String readFile(String filePath) throws IOException {
// 读取文件的代码
}
@deprecated
用于标记方法、类或字段已经不推荐使用,通常伴随着一段描述替代方案的说明
/**
* @deprecated 不推荐使用,请使用新的方法 {@link #newMethod()}
*/
@Deprecated
public void oldMethod() {
// 旧方法的实现
}
@see
用于提供对其他类、方法或字段的引用
/**
* 查看 {@link OtherClass} 类的文档
*/
public void seeOtherClass() {
// ...
}
@link
与@see
类似,用于创建超链接
/**
* 请参考 {@link #add(int, int)} 方法
*/
public void referToAddMethod() {
// ...
}
@inheritDoc
用于继承文档注释,表示子类或实现类应该继承父类或接口的文档注释
/**
* {@inheritDoc}
* 新增了一些额外的说明
*/
@Override
public void someMethod() {
// 实现方法
}
这些注释标签在Javadoc中被解析,并用于生成详细的API文档,帮助开发者理解和使用代码。使用这些标签可以提高文档的质量,使得生成的文档更加详尽和规范。
总结:通过运用不同类型的注释,我们能够更好地组织和解释代码,使得代码更易读、易懂。在实际开发中,良好的注释是团队协作和代码维护的关键。