PHPDoc的冗长性难道不是值得的吗？

Question

我今天第一次尝试使用PHPDoc，但很快遇到了问题。

对于每1行变量声明，我至少有5行注释。例：

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

当然，收益是不错的-但这会将10行的配置文件转换为60行的文件。需要我一辈子来填写，但我还不相信它会在简单的单行代码中增加很多。

这也给我的工作流程带来了麻烦。在我需要进行彻底更改之前，一切都很好。有了我记录良好的文档块，我突然不再需要重构代码，而是需要重写所有这些繁琐的细节。等到你说完为止？哈！这样，文档将永远不会发生。

最重要的是-它迫使我在代码中间使用C风格的/ ** /注释。这使我在开发过程中发疯，因为它剥夺了按需注释掉大块内容的能力。现在注释掉一大段代码，我需要拉出类似：range，s / ^ /＃/;的代码。然后稍后撤消。烦人！

长话短说-我喜欢PHPDoc，我喜欢记录良好的代码-但是每一行代码只有5行注释！。有我缺少的功能吗？这是个常见的问题吗？

Answer 1

它是否过大很大程度上取决于应用程序的预期用途。如果您要编写仅由单个公司或公司使用的应用程序，则可能不需要详尽的文档说明每个变量。

例如，现在我正在一个具有相当广泛的代码库但很少有开发人员的项目（目前仅我一个人）。我为两件事添加了PHPDoc块：类和方法。对于其他所有内容，我都会经常发表评论，但请不要使用冗长的PHPDoc格式。大部分代码只有三到四个人才能看到，他们需要的信息是黑匣子信息：我向该方法发送了什么，我希望从中获得什么。他们想知道如何从模型中获取数据，而不是私有类变量的用途。

如果我正在编写打算分发给其他开发人员或公司的应用程序，并且希望他们将我的应用程序与其他系统集成或扩展其功能，那么我将在更广泛的PHPDoc使用上赋予更多价值。在长期维护期间，此类细节绝对可以派上用场。

举例来说，我当前的项目有时会要求创建一个可从其他站点访问的API。您可以打赌，API比代码行包含更多的注释和书面文档。