PHPDoc 冗长是否比它的价值更麻烦？ [关闭]

Question

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

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

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

当然，回报是不错的——但这会将一个 10 行的配置文件变成一个 60 行的文件。需要我永远填写，而且我还不相信它比简单的单行增加了那么多。

这也给我的工作流程带来了麻烦。一切都很好，直到我需要进行彻底的改变。有了我记录良好的文档块，突然之间我不再需要重构我的代码，但我需要重新编写所有这些繁琐的细节。等到你说的最后？哈哈！那么文档将永远不会发生。

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

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

Answer 1

它是否矫枉过正在很大程度上取决于您的应用程序的预期用途。如果您正在编写一个仅供单个公司或团体使用的应用程序，您可能不需要每个变量的详尽文档。

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

如果我正在编写一个打算分发给其他开发人员或公司的应用程序，并且我希望他们将我的应用程序与其他系统集成或扩展其功能，那么我会更加重视更广泛的 PHPDoc 使用。在长期维护期间，这种细节肯定会派上用场。

举个例子，我当前的项目有时需要创建一个 API 才能从其他站点访问。您可以打赌，API 将拥有比代码行更多的 cmets 和书面文档。