什么时候应该记录例外情况？

Question

假设以下片段：

public function foo() 
{
    return $this->dependency->bar();
}

如果已知 dependency::bar() 会抛出异常，但预计 foo() 不会处理它。 foo() 的文档块中是否应该有一个 @throws 条目？或者这应该是隐含的？ phpdoc 文档对此有些含糊。

假设dependency是基于接口注入；接口文档是否应说明方法 可以 抛出指定的异常。

异常应该由调用代码处理还是与情况无关重要？

一路语义:)

Answer 1

您已经创建了 public 函数（每个人都可以使用它），它在某些情况下会抛出异常 - 因此您肯定必须在您的文档块中包含 @throws 条目。
如果您的依赖项抛出异常 - 这是您的内部实现并且它是封装的 - 因此将使用您的函数的人将不知道您的函数有什么期望。

在接口注入的情况下 - 接口必须描述所有异常，因为异常是 class 行为的一部分，接口必须描述所有可能的行为。

如果您有 try-catch 块并处理来自依赖项的所有异常 - 您必须在文档块的 @throws 条目中只有您自己的异常。