JavaDoc警告可能存在NullPointerException

Question

我编写了一种返回Android上最可能的LAN接口的方法。由于用户可能未连接到LAN，因此此方法可能返回null。我应该如何在JavaDoc中警告呼叫者这种可能性？我不认为我应该使用@throws，因为该方法实际上不会抛出NullPointerException。

Answer 1

我认为正确的方法是在return子句中：

/**
 * ...
 * @return {@code null} if the user is not connected to a LAN, else the most
 * likely LAN interface.
 */
public LanInterface getMostLikelyInterface();

调用者有责任知道这意味着在检查之前不使用返回的值。

虽然您可以使用Guavas的Optional课程来代替：

/**
 * ...
 * @return Optional.absent if the user is not connected to a Lan interface,
 *    else the most likely one.
 */
public Optional<LanInterface> getMostLikelyInterface();

然后，用户必须使用if(iface.isPresent())，这比if(iface != null)更具可读性。