是否应该在 JavaDoc 中描述未经检查的异常？答案

【问题标题】：Should unchecked Exception be described in JavaDoc?是否应该在 JavaDoc 中描述未经检查的异常？
【发布时间】：2018-11-02 03:57:59
【问题描述】：

我有以下代码：

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);
    }
}

根据Oracle：

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

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

【问题讨论】：

如果使用你的函数的人被告知它可能会抛出这个异常，这会有用吗？这就是 javadocs 的用途。您可以将@throws 或@exception 用于未检查的异常以及已检查的异常。
Oracle 声明它不需要在此处进行描述。它没有被禁止或气馁。你仍然可以这样做，我认为这是正确的做法。
这里是一个来自 JDK 的例子：docs.oracle.com/javase/7/docs/api/java/lang/…
@Michael 我希望doesUserExist 返回一个布尔值。我希望checkUserExists 会引发异常。
我同意赫尔伍德的观点。但我认为创建返回信息而不是引发异常来通知调用者的方法是一个更好的设计。所以我认为拥有一个返回布尔值的函数doesUserExists() 将是一个更好的设计。例外是通知异常行为/数据，在您的情况下，如果用户存在，您会创建一个函数来检查，这意味着您希望有时它不存在，因此没有用户是不正常的。所以我会返回一个布尔值而不是异常。如果调用者期望用户存在，调用者可以抛出异常

标签： java javadoc

【解决方案1】：

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

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

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

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

【讨论】：