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

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

根据oracle：

  

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

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

提前谢谢！

Answer 1

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

在您的情况下，如果找不到用户，用户似乎确实知道引发NoUserFoundException确实很有用。

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

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