是否需要在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); 
    } 
}

根据Oracle官方文档的说明：

“非受检异常若由方法或构造方法执行抛出并传播至外部，无需在throws子句中声明。”

是否需要在JavaDoc中描述该非受检异常？ #

当然需要。虽然编译器不强制声明非受检异常，但对于调用这个方法的开发者来说，完全不知道这个方法可能抛出NoUserFoundException是很危险的——尤其是这种业务逻辑相关的非受检异常，不像NullPointerException这类通用异常，调用者需要明确知道触发条件才能提前做防御性处理或者捕获处理。忽略这一点会让调用方的代码更容易出现意外崩溃。

在JavaDoc中描述此类非受检异常的最佳方式（不使用@throws注解） #

如果你不想用@throws注解，推荐这些实用做法：

• 在方法的JavaDoc功能描述末尾，直接补充异常触发场景：比如写 /** 根据用户ID查询用户信息。当传入的ID为null或不存在对应用户时，会抛出NoUserFoundException异常。 */
• 可以单独用一段文字专门梳理异常情况，保持结构清晰：

  /**
   * 根据用户ID查询用户信息
   * 
   * 此方法会先校验用户是否存在，若校验不通过则抛出非受检异常。
   * 触发异常的具体场景：
   * 1. 传入的id参数为null
   * 2. 数据库中不存在对应id的用户记录
   */
  

• 描述时要明确指出异常类型和触发条件，别用模糊表述，让调用者能精准理解风险点。

内容的提问来源于stack exchange，提问作者trap