Java方法注释中应只写throws声明的受检异常，运行时异常除非明确作为契约行为否则不写；@throws须说明触发条件而非仅列类型；自定义异常需详述字段语义与构造逻辑；工具链应强制文档与代码一致。
Java异常该不该在方法注释里写 throws
应该写，但只写 throws 声明的受检异常（checked exception），且必须和实际签名一致。运行时异常（RuntimeException 及其子类）不强制写进 @throws，写了反而误导调用方以为必须处理。
常见错误是把 NullPointerException、IllegalArgumentException 一股脑塞进 Javadoc，结果导致文档膨胀、重点模糊，还让读者误以为这些异常是 API 合约的一部分。
-
@throws IOException—— 必须写，因为FileInputStream构造器声明了它 -
@throws IllegalArgumentException—— 可选，仅当该异常是方法逻辑中明确校验并抛出的“业务边界信号”（如传入负数 ID） -
@throws NullPointerException—— 不写，除非你主动if (obj == null) throw new NullPointerException()并把它当作契约行为（极少见）
Javadoc 中如何描述异常触发条件
关键不是罗列异常类型，而是说明「什么输入或状态会导致它」。调用方真正需要的是可预测性，不是异常分类学。
差的写法：@throws IOException if something goes wrong；好的写法：@throws IOException if the file does not exist or is not readable。
- 用具体动词：「is not readable」比「cannot be accessed」更准
- 避免模糊短语：删掉
unexpectedly、due to internal error这类无信息量的描述 - 如果异常由下游抛出，需注明来源：例如
@throws SQLException if the underlying JDBC driver throws it during commit
自定义异常类的文档要点
自定义异常不是写个空类就完事。它的构造函数、字段、getMessage() 行为，都得在 Javadoc 里说清语义。
尤其注意：不要让 getMessage() 返回堆栈片段、原始 SQL 或未脱敏的路径——这些内容可能泄露系统细节，也违背异常信息应面向开发者而非终端用户的定位。
- 每个公共构造函数都要有
@param和@throws（如果它自己会抛异常） - 若异常含业务字段（如
errorCode、retryAfter），必须在字段 Javadoc 中说明取值范围与含义 - 重写
toString()或getLocalizedMessage()的，要同步更新文档，否则使用者会按默认行为理解
/**
* Thrown when a payment attempt exceeds the allowed retry limit.
* {@code retryCount} is guaranteed to be >= {@code maxRetries}.
*/
public class PaymentRetryExhaustedException extends Exception {
private final int retryCount;
private final int maxRetries;
<pre class="brush:java;toolbar:false;">/**
* @param retryCount number of attempts already made
* @param maxRetries maximum allowed attempts before rejection
*/
public PaymentRetryExhaustedException(int retryCount, int maxRetries) {
super("Payment rejected: " + retryCount + "/" + maxRetries + " retries exhausted");
this.retryCount = retryCount;
this.maxRetries = maxRetries;
}
}
IDE 和静态检查工具怎么配合异常文档
光靠人写文档不可靠。要用工具守住底线：比如要求所有 throws 声明必须有对应 @throws，或禁止在 Javadoc 里写未声明的受检异常。
IntelliJ 默认会警告缺失的 @throws 标签；SpotBugs 的 DCN_NULLPOINTER_EXCEPTION 规则能揪出空指针被误标为契约异常的问题。更重要的是，把 mvn javadoc:javadoc 加进 CI 流程，让文档缺失或不一致直接导致构建失败。
- 启用 Maven Javadoc 插件的
failOnError和additionalOptions（如-Xdoclint:all,-missing） - 在
@throws后面加{@link MyCustomException}而不是纯文本，确保链接可跳转、可验证 - 团队内统一禁用
@exception（过时标签），只用@throws
最难的不是写清楚某一个异常，而是让整个模块的异常语义连贯：哪些是流程分支，哪些是故障信号，哪些该重试，哪些该告警——这些判断最终都会沉淀在注释和文档里，而不是代码行间。漏掉一处，下游就多一分猜测成本。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
