PHPDoc的冗长程度是否比它值得的麻烦更多？ [英] Is PHPDoc verbosity more trouble than it's worth?
问题描述
我今天第一次尝试使用PHPDoc，很快就遇到了问题。
每1行变量声明中，我至少有5行注释。示例：
/ **
*保存远程服务器
的路径* @name ...
* @global ...
* /
$ myvar = ...
当然，收益很好-但这会将10行的配置文件转换为60行的文件。我花了很长时间来填写，但我还不相信它会在简单的单行代码中增加很多。
这也给我的工作流程带来了麻烦。在我需要进行彻底更改之前，一切都很好。有了文档齐全的文档块，我突然不必再重构代码，而是需要重新编写所有这些繁琐的细节。等到你说完为止？哈！
最重要的是-它迫使我在代码中间使用C风格的/ ** /注释。这使我在开发过程中发疯，因为它剥夺了按需注释掉大块内容的能力。现在注释掉一大段代码，我需要提取类似：range，s / ^ /＃/;的代码。然后稍后撤消。
长话短说-我喜欢PHPDoc，我喜欢有据可查的代码-但是每一行代码有5行注释是太多了！ 。有我缺少的功能吗？这是一个常见的问题吗？
是否过度使用它在很大程度上取决于应用程序的预期用途。如果您要编写仅由单个公司或公司使用的应用程序，则可能不需要详尽的文档记录每个变量。
例如，目前，我正在一个具有相当广泛的代码库但很少有开发人员的项目（目前仅我一个人）。我要为两件事添加PHPDoc块：类和方法。对于其他所有内容，我都会经常评论，但不会采用冗长的PHPDoc格式。大部分代码只有三到四个人才能看到，他们需要的信息是黑匣子信息：我向该方法发送了什么，我希望从中获得什么。他们想知道如何从模型中获取数据，而不是私有类变量的用途。
如果我正在编写打算分发给其他开发人员的应用程序或公司，而我希望他们将我的应用程序与其他系统集成或扩展其功能，那么我将在更广泛的PHPDoc使用上获得更多价值。这类细节在长期维护期间肯定可以派上用场。从其他站点。您可以打赌，与代码行相比，API将有更多的注释和书面文档。
I tried using PHPDoc for the first time today and quickly ran into a problem.
For every 1 line of variable declarations, I had at least 5 lines of comments. Example:
/**
* Holds path the remote server
* @name ...
* @global ...
*/
$myvar = ...
Of course, the payoffs are nice - but this turns a 10-line config file into a 60-line file. Takes me forever to fill out, and I'm not yet convinced it adds that much over a simple one-liner.
It also throws a kink in my workflow. All is fine and good until I need to make sweeping changes. With my well-documented doc-blocks, all of a sudden I no longer have to refactor my code, but I need to re-write all these tedious details. Wait til the end you say? HAH! Then documentation will never happen.
On top of it all - it forces me into C-style /**/ comments in the middle of my code. This drives me crazy during development since it strips the ability to comment out large blocks on demand. Now to comment out a a large block of code, I need to pull something like :range,s/^/#/ ; then undo it later. Annoying!
Long story short - I like PHPDoc, I love well documented code - but 5 lines of comments for every one line of code is far too much!. Are there features I'm missing? Is this a common problem?
Whether or not it's overkill depends largely on the intended use of your application. If you're writing an app that will only be used by a single company or group, you probably don't need exhaustive documentation of every single variable.
For example, right now I'm working on a project with a fairly extensive code base but very few developers (for now, just me). I'm adding PHPDoc blocks for two things: classes and methods. For everything else, I comment frequently, but not in verbose PHPDoc format. Most of this code will only ever be seen by three or four people, and the information they're going to need is black box info: what do I send to this method, what do I expect to get out of it. They want to know how to get data from a Model, not what an private class variable is for.
If I were writing an app that I intended to distribute to other developers or companies, and I expected them to integrate my app with other systems or extend its functionality, I would place more value on more extensive PHPDoc use. That kind of detail could definitely come in handy during long-term maintenance.
Case in point, my current project will at some point require the creation of an API to be accessed from other sites. You can bet that API will have more comments and written documentation than lines of code.
这篇关于PHPDoc的冗长程度是否比它值得的麻烦更多？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
