java - 我应该在 javadoc 中写多个 @return 标签吗

Question

假设我有一个返回字符串数组的 java 方法。在方法内部，我有多个返回语句，具体取决于条件。

public String[] userLogIn() {
    String[] success = {"You", "are", "the", "king"};
    String[] errorMsg = {"You", "are", "nothing"};
    double ran = Math.random();
    if(ran < 0.33)
        return success;
    else if (ran < 0.66)
        return errorMsg;
    else
        return null;
}

这个例子可能太天真了。但我的观点是，我应该/可以使用多个@return 标签，比如 @return this array 如果满足条件 1 @return 如果满足条件 2，则返回该数组 @return null 如果满足条件 3 ？

我经常写一个 @return the login message 但我认为当返回 null 时这就没有意义了。 一般而言，哪种方式是更好的编码实践？

Answer 1

在 Javadoc 注释中只能有一个 @return 标签。 Javadoc 是为使用您的方法的人编写的。它应该描述什么方法做了什么，而不是如何它做了。方法中 return 语句的数量与文档阅读器完全无关，唯一相关的是你的方法为什么输入返回什么。

在您的情况下，您可以按如下方式记录您的示例方法:

/** 
 * Logs in the user.
 *
 * @return the result of the operation if the logging in is successful, or
 *         an error message describing the failure if it is not
 */
public String[] userLogIn() {
    ...
}