应该在 JavaDoc 中描述 unchecked Exception 吗？

Question

我有以下代码：

public User getUserById(Long id) {
checkUserExists(id);
return repo.findOne(id);
}

private void checkUserExists(Long id) {
    if (id == null || !repo.exists(id)) {
        throw new NoUserFoundException("No User exists with id: " +id);
    }
}

根据甲骨文：

“如果未经检查的异常可以通过方法或构造函数的执行抛出并传播到方法或构造函数边界之外，则不需要在方法或构造函数的 throws 子句中声明它们。”

我是否必须在 JavaDoc 中描述异常（没有@throws子句，但只描述？）在 JavaDoc 中描述这种未经检查的异常的最佳方法是什么？

Answer 1

您正在为您的方法的用户编写 Javadoc。如果该用户知道它可能会抛出异常有用，请记录它！

在您的情况下，NoUserFoundException如果未找到用户，则用户知道抛出a 似乎确实很有用。

在其他情况下，它不太有用。例如，在许多情况下，NullPointerException如果参数为空则抛出 a的事实并未记录在 Javadoc 中，因为它通常以某种方式暗示参数不能为空。

顺便说一下，Oracle 谈论的是throws出现在方法声明之后的类，而不是 Javadoc。如果您决定记录非检查异常，则使用该@throws子句是有意义的。