Idea开发代码注释规范

规范

1. 类注释：每个类都应该有一个简短的注释，描述这个类的用途和主要功能。注释应该放在类的声明之前，使用JavaDoc格式。

/**
 * 这是一个示例类，用于演示如何编写类注释。
 */
public class ExampleClass {
    // ...
}

2. 方法注释：每个方法也应该有一个简短的注释，描述这个方法的功能、输入参数、返回值以及可能抛出的异常。注释应该放在方法声明之前，使用JavaDoc格式。

/**
 * 计算两个整数的和。
 *
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两个整数的和
 */
public int add(int a, int b) {
    return a + b;
}

3. 变量注释：对于复杂的变量或需要解释的变量，应该在声明时添加注释。注释应该简洁明了，说明变量的作用和含义。

/**
 * 存储用户的名字
 */
private String userName;

4. 常量注释：对于常量（如静态final字段），应该在声明时添加注释，说明常量的用途和含义。

/**
 * π的值，用于圆周率计算
 */
public static final double PI = 3.141592653589793;

5. 内部类注释：如果有必要，可以为内部类添加注释，描述其作用和功能。

/**
 * 内部类，用于处理字符串操作
 */
public class StringHandler {
    // ...
}

6. 注释风格：尽量保持注释简洁明了，避免过多的冗余信息。注释应该遵循一致的风格，例如使用英文标点符号和空格。

7. 注释更新：当代码发生变化时，确保相应的注释也得到更新，以保持代码和注释的一致性。

如何在方法注释中引用其他类？

在Java中，使用JavaDoc注释来文档化代码时，如果需要引用其他类或方法，有几种标准格式可以使用。这些引用格式可以让生成的HTML文档中包含相应的链接，从而方便地导航到引用的类或方法的文档页面。

1. 类引用：

/**
 * 这个类用于处理{@link com.example.Project}项目的事务.
 */
public class ProjectManager {
    // ...
}

如下StringBuilder源码所示：

2. 方法引用：

/**
 * 这个方法用于获取项目的状态.
 * 它使用了{@link #getStatus(int)}方法来获取状态信息.
 */
public String getProjectStatus(Project project) {
    // ...
}

/**
 * 获取项目的状态码.
 *
 * @param projectId 项目的ID
 * @return 状态码
 */
private int getStatus(int projectId) {
    // ...
}

如下StringBuilder源码所示：

3. 参数引用：

/**
 * 将指定的{@code user}添加到{@code project}中.
 *
 * @param user 要添加的用户
 * @param project 项目对象
 */
public void addUserToProject(User user, Project project) {
    // ...
}

如下StringBuilder源码所示：

4. 包及类或方法的完全限定名：

/**
 * 处理 {@link com.example.project.Project#getStatus(int)} 方法抛出的异常.
 */
public void handleException() {
    // ...
}

5. 通用注解：

/**
 * {@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;
}

6. 在注释中使用@see和@link标签可以创建指向其他类、方法或属性的超链接。@see通常用于参考相关的类或方法，而@link用于创建即时链接。

/**
 * 使用 {@link com.example.OtherClass#otherMethod()} 方法来初始化数据.
 * @see #initializeData() 用于数据初始化的方法
 */
public void setup() {
    // ...
}

7. 注意事项：

• @link标签内可以直接使用#来定义要链接到的方法或属性。
• @see标签后面通常跟着完全限定的类、方法或属性名称，并且可以包含多个参考。
• {@code}标签用于指出代码样本，它会在生成的HTML中以等宽字体显示。
• {@link}和@see标签在生成的HTML文档中会转换为相应的超链接。