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): 初始版本*/
遵循这些原则可以生成专业、易读的项目文档，同时提高代码的可维护性。