Java 文件注释规范（便于生成项目文档）

良好的 Java 文件注释不仅能帮助生成项目文档，还能提高代码可维护性。以下是 Java 文件注释的最佳实践：

1. 文件头注释（Class/Interface 级别）

每个 Java 文件顶部应包含类/接口的文档注释：

/**
 * 类/接口的功能描述
 * 
 * <p>详细描述类的核心功能、设计目的和使用场景</p>
 * 
 * @author 作者姓名 (可选)
 * @version 版本号 (可选)
 * @since 引入版本 (可选)
 * @see 相关类/方法 (可选)
 */
public class ExampleClass {
    // 类实现
}

示例：控制器类注释

/**
 * 用户管理控制器
 * 
 * <p>提供用户相关的RESTful API，包括用户注册、登录、信息查询等功能</p>
 * 
 * @author ZhangSan
 * @version 1.0
 * @since 2023-03-01
 * @see UserService
 */
@Path("/api/users")
public class UserController extends Controller {
    // 方法实现
}

2. 方法注释

每个公共方法应有详细注释：

/**
 * 方法功能描述
 * 
 * <p>详细说明方法的作用、算法、边界条件等</p>
 * 
 * @param 参数名 参数说明
 * @return 返回值说明
 * @throws 异常类型 异常说明
 */
public ReturnType methodName(ParamType param) throws ExceptionType {
    // 方法实现
}

示例：服务方法注释

/**
 * 用户登录验证
 * 
 * <p>根据用户名和密码验证用户身份，验证成功返回用户信息</p>
 * 
 * @param username 用户名(长度4-20字符)
 * @param password 密码(MD5加密后的字符串)
 * @return 登录成功的用户对象，包含基本信息和token
 * @throws AuthException 当用户名或密码错误时抛出
 */
public User login(String username, String password) throws AuthException {
    // 方法实现
}

3. 字段/常量注释

重要字段和常量应有注释：

/** 最大登录尝试次数 */
private static final int MAX_LOGIN_ATTEMPTS = 5;

/** 用户服务实例 */
@Inject
private UserService userService;

4. 注释内容原则

1. ​​简洁准确​​：避免冗长，用最简练的语言描述 ​​
2. 说明"为什么"​​：而不仅仅是"做什么"
3. ​​避免重复​​：不要重复方法名/参数名已表达的信息 ​​
4. 特殊说明​​：包括线程安全、性能考虑等 ​​
5. 使用HTML标签​​：如 "< p>, < code>, < pre >" 等格式化文档

5. 常用Javadoc标签

标签	用途	示例
@param	方法参数说明	@param username 用户名
@return	返回值说明	@return 操作是否成功
@throws	异常说明	@throws IOException 当文件不存在时
@see	相关参考	@see UserService#updateUser
@since	引入版本	@since 1.2
@deprecated	已废弃	@deprecated 使用{@link #newMethod}替代

6. 文档生成工具

6.1.标准Javadoc​​：

javadoc -d docs -sourcepath src -subpackages com.example

6.2.​​Maven插件​​：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.3.2</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

运行：

mvn javadoc:javadoc

7. 高级技巧

7.1.​​交叉引用​​：

/**
 * 类似{@link #methodName}，但针对批量操作
 */

7.2.​​代码示例​​：

/**
 * <pre>{@code
 * // 使用示例
 * User user = service.login("admin", "123456");
 * }</pre>
 */

7.3.​​版本变更记录​​：

/**
 * @version 1.1
 * @changelog
 * - 1.1 (2023-03-15): 增加多因素认证支持
 * - 1.0 (2023-01-10): 初始版本
 */

遵循这些原则可以生成专业、易读的项目文档，同时提高代码的可维护性。