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.
发布评论
评论（1）
它是否过度杀伤力很大程度上取决于应用程序的预期用途。 如果您正在编写一个仅由单个公司或团体使用的应用程序，您可能不需要每个变量的详尽文档。
例如，现在我正在开发一个具有相当广泛的代码库但开发人员很少的项目（目前只有我）。 我为两件事添加 PHPDoc 块：类和方法。 对于其他一切，我经常发表评论，但不是以冗长的 PHPDoc 格式。 大部分代码只会被三四个人看到，他们需要的信息是黑匣子信息：我要向这个方法发送什么，我希望从中得到什么。 他们想知道如何从模型获取数据，而不是私有类变量的用途。
如果我正在编写一个应用程序，打算分发给其他开发人员或公司，并且我希望他们将我的应用程序与其他系统集成或扩展其功能，那么我会更重视更广泛的 PHPDoc 使用。 这种细节在长期维护过程中肯定会派上用场。
举个例子，我当前的项目有时会需要创建一个可以从其他站点访问的 API。 您可以打赌，API 的注释和书面文档将比代码行还要多。
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.