是否应在方法文档中添加@throws？间接抛出异常时需标注吗？

这是个日常写代码时很容易纠结的文档注释问题，我来帮你理清楚：

核心判断原则：看当前方法是否让异常直接向外传播 #

一句话总结：如果你的myMethod没有捕获aMethod抛出的MyException，而是让它直接传递给myMethod的调用者，那么应该手动添加@throws MyException标签；如果myMethod捕获了这个异常并做了处理（比如转成其他异常、记录日志后不再抛出），那就完全不需要加。

为什么PHPStorm不会自动添加这个标签？ #

PHPStorm的自动生成逻辑偏保守，它默认只会识别当前方法内部显式写出的throw语句（比如ClassOne::aMethod里直接throw new MyException()这种）。对于通过调用其他方法间接传递的异常，它不会自动推断添加——毕竟你随时可能给myMethod加上try/catch块来处理这个异常，IDE没法提前预判你的意图。

手动添加的好处：从规范和实用性角度看 #

• 给调用者明确的预期：其他开发者调用myMethod时，不用去翻底层aMethod的源码，看当前方法的DocBlock就知道可能会抛出MyException，能提前做好异常处理。
• 符合文档注释的初衷：DocBlock的核心是描述当前方法的行为，包括它可能产生的副作用（比如抛出异常）。不管这个异常是自己抛的还是从其他方法传过来的，只要当前方法会把它抛出去，就属于当前方法的行为一部分。
• IDE支持更友好：手动添加后，PHPStorm等IDE会在调用myMethod时给出异常提示，帮开发者避免遗漏异常处理逻辑。

两种场景的代码示例对比 #

场景1：不捕获异常，需要加@throws

class ClassTwo{ 
/** 
* 调用ClassOne的aMethod方法，异常会直接向上传递
* 
* @throws MyException 当aMethod触发异常时，该异常将被传递给当前方法的调用者
* @return void 
*/ 
public function myMethod() { 
    $classOne = new ClassOne(); 
    $classOne->aMethod(); // 异常未被处理，直接向外传播
} 
}

场景2：捕获异常，不需要加@throws

class ClassTwo{ 
/** 
* 调用ClassOne的aMethod方法并内部处理异常
* 
* @return void 
*/ 
public function myMethod() { 
    $classOne = new ClassOne(); 
    try {
        $classOne->aMethod(); 
    } catch (MyException $e) {
        // 内部处理异常，比如记录日志
        error_log("调用aMethod出错：{$e->getMessage()}");
    }
} 
}

总结 #

如果你的方法没有处理调用方法抛出的异常，而是让它继续传播，强烈建议手动补充@throws标签。这会让你的代码文档更清晰，也能帮其他开发者更顺畅地使用你的方法。PHPStorm没自动加只是因为它没法100%确定你的意图，这时候就需要我们手动完善文档啦。

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