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将包含比代码行更多的注释和书面文档。