我今天第一次尝试使用 PHPDoc，很快就遇到了问题。
每 1 行变量声明，我至少有 5 行注释。例子：
/**
* Holds path the remote server
* @name ...
* @global ...
*/
$myvar = ...
当然，回报是不错的 - 但这会将 10 行配置文件变成 60 行文件。我花了很长时间才填写完，而且我还不相信它比简单的一行字能增加那么多。
这也给我的工作流程带来了麻烦。一切都很好，直到我需要进行彻底的改变。有了我记录良好的文档块，突然间我不再需要重构我的代码，但我需要重新编写所有这些乏味的细节。你说要等到最后吗？哈！那么文档将永远不会发生。
最重要的是 - 它迫使我在代码中间使用 C 风格的 /**/ 注释。这让我在开发过程中发疯，因为它剥夺了按需注释大块的能力。现在要注释掉一大块代码，我需要提取类似 :range,s/^/#/ 的内容；然后稍后撤消它。恼人的！
长话短说 - 我喜欢 PHPDoc，我喜欢有详细文档的代码 - 但是每行代码 5 行注释是太多了！。有我缺少的功能吗？这是个常见的问题吗？
它是否过度杀伤力很大程度上取决于应用程序的预期用途。如果您正在编写一个仅由单个公司或团体使用的应用程序，您可能不需要每个变量的详尽文档。
例如，现在我正在开发一个具有相当广泛的代码库但开发人员很少的项目（目前只有我）。我为两件事添加 PHPDoc 块：类和方法。对于其他一切，我经常发表评论，但不是以冗长的 PHPDoc 格式。大部分代码只会被三四个人看到，他们需要的信息是黑匣子信息：我要向这个方法发送什么，我希望从中得到什么。他们想知道如何从模型获取数据，而不是私有类变量的用途。
如果我正在编写一个应用程序，打算分发给其他开发人员或公司，并且我希望他们将我的应用程序与其他系统集成或扩展其功能，那么我会更重视更广泛的 PHPDoc 使用。这种细节在长期维护过程中肯定会派上用场。
举个例子，我当前的项目有时会需要创建一个可以从其他站点访问的 API。您可以打赌，API 的注释和书面文档将比代码行还要多。
本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)
