规范
- 类注释：每个类都应该有一个简短的注释，描述这个类的用途和主要功能。注释应该放在类的声明之前，使用JavaDoc格式。
/**
* 这是一个示例类，用于演示如何编写类注释。
*/
public class ExampleClass {
// ...
}
- 方法注释：每个方法也应该有一个简短的注释，描述这个方法的功能、输入参数、返回值以及可能抛出的异常。注释应该放在方法声明之前，使用JavaDoc格式。
/**
* 计算两个整数的和。
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的和
*/
public int add(int a, int b) {
return a + b;
}
- 变量注释：对于复杂的变量或需要解释的变量，应该在声明时添加注释。注释应该简洁明了，说明变量的作用和含义。
/**
* 存储用户的名字
*/
private String userName;
- 常量注释：对于常量（如静态final字段），应该在声明时添加注释，说明常量的用途和含义。
/**
* π的值，用于圆周率计算
*/
public static final double PI = 3.141592653589793;
- 内部类注释：如果有必要，可以为内部类添加注释，描述其作用和功能。
/**
* 内部类，用于处理字符串操作
*/
public class StringHandler {
// ...
}
-
注释风格：尽量保持注释简洁明了，避免过多的冗余信息。注释应该遵循一致的风格，例如使用英文标点符号和空格。
-
注释更新：当代码发生变化时，确保相应的注释也得到更新，以保持代码和注释的一致性。
如何在方法注释中引用其他类？
在Java中，使用JavaDoc注释来文档化代码时，如果需要引用其他类或方法，有几种标准格式可以使用。这些引用格式可以让生成的HTML文档中包含相应的链接，从而方便地导航到引用的类或方法的文档页面。
- 类引用：
/**
* 这个类用于处理{@link com.example.Project}项目的事务.
*/
public class ProjectManager {
// ...
}
如下StringBuilder源码所示：
- 方法引用：
/**
* 这个方法用于获取项目的状态.
* 它使用了{@link #getStatus(int)}方法来获取状态信息.
*/
public String getProjectStatus(Project project) {
// ...
}
/**
* 获取项目的状态码.
*
* @param projectId 项目的ID
* @return 状态码
*/
private int getStatus(int projectId) {
// ...
}
如下StringBuilder源码所示：
- 参数引用：
/**
* 将指定的{@code user}添加到{@code project}中.
*
* @param user 要添加的用户
* @param project 项目对象
*/
public void addUserToProject(User user, Project project) {
// ...
}
如下StringBuilder源码所示：
- 包及类或方法的完全限定名：
/**
* 处理 {@link com.example.project.Project#getStatus(int)} 方法抛出的异常.
*/
public void handleException() {
// ...
}
- 通用注解：
/**
* {@summary This method calculates the sum of two integers. }
* {@param a The first integer in the addition.}
* {@param b The second integer in the addition.}
* {@return The sum of {@code a} and {@code b}.}
*/
public int add(int a, int b) {
return a + b;
}
- 在注释中使用
@see和@link标签可以创建指向其他类、方法或属性的超链接。@see通常用于参考相关的类或方法，而@link用于创建即时链接。
/**
* 使用 {@link com.example.OtherClass#otherMethod()} 方法来初始化数据.
* @see #initializeData() 用于数据初始化的方法
*/
public void setup() {
// ...
}
- 注意事项：
@link标签内可以直接使用#来定义要链接到的方法或属性。@see标签后面通常跟着完全限定的类、方法或属性名称，并且可以包含多个参考。{@code}标签用于指出代码样本，它会在生成的HTML中以等宽字体显示。{@link}和@see标签在生成的HTML文档中会转换为相应的超链接。
