时间戳

首页 > 解决方案 > 是否应该在 JavaDoc 中描述未经检查的异常？

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

问题描述

我有以下代码：

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 中描述这种未经检查的异常的最佳方法是什么？

标签： javajavadoc

解决方案

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

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

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

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

推荐阅读