<分区>
我今天第一次尝试使用 PHPDoc，很快就遇到了问题。
对于每 1 行变量声明，我至少有 5 行注释。示例:
/**
* Holds path the remote server
* @name ...
* @global ...
*/
$myvar = ...
当然，返回不错 - 但这会将 10 行的配置文件变成 60 行的文件。我花了很长时间才填满，而且我还不相信它比简单的一行增加了那么多。
它还会给我的工作流程带来麻烦。一切都很好，直到我需要进行彻底的改变。有了文档完善的文档 block ，突然间我不再需要重构我的代码，但我需要重写所有这些繁琐的细节。你说等到最后？哈!那么文档将永远不会发生。
最重要的是 - 它迫使我在代码中间使用 C 风格的/**/注释。这让我在开发过程中发疯，因为它剥夺了按需注释掉大块的能力。现在要注释掉一大块代码，我需要提取类似 :range,s/^/#/的内容；然后稍后撤消它。烦人!
长话短说 - 我喜欢 PHPDoc，我喜欢文档齐全的代码 - 但是每一行代码的 5 行注释太多了!。有没有我缺少的功能？这是一个常见问题吗？
最佳答案
它是否矫枉过正在很大程度上取决于您的应用程序的预期用途。如果您正在编写仅供单个公司或团体使用的应用程序，您可能不需要对每个变量都进行详尽的记录。
例如，现在我正在从事一个代码库相当广泛但开发人员很少(目前只有我)的项目。我为两件事添加了 PHPDoc block :类和方法。对于其他一切，我经常评论，但不是冗长的 PHPDoc 格式。这段代码的大部分只会被三四个人看到，他们需要的信息是黑盒信息:我向这个方法发送了什么，我希望从中得到什么。他们想知道如何从模型中获取数据，而不是私有(private)类变量的用途。
如果我正在编写一个我打算分发给其他开发人员或公司的应用程序，并且我希望他们将我的应用程序与其他系统集成或扩展其功能，我会更加重视更广泛的 PHPDoc 使用。这种细节在长期维护中肯定能派上用场。
例如，我当前的项目在某个时候需要创建一个 API 以便从其他站点访问。您可以打赌，API 的注释和书面文档将比代码行更多。
关于php - PHPDoc 的冗长是否比它的值(value)更麻烦？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/805084/