CakePHP 代码中的注释真的有用/有必要吗？
通读核心并查看几乎所有可用的帮助程序/插件等，我注意到有很多评论。
CakePHP 的结构使得可以非常简单地确定事物在哪里以及它们在做什么。真的有必要对所有这些代码进行注释吗？它会让源代码变得更加混乱还是真的有用？当您理解这些评论时，您发现它们有用吗？或者你读过它们吗？
更新：以下是从 CakePHP Core 连接管理器获取的注释示例：
/**
* Loads the DataSource class for the given connection name
*
* @param mixed $connName A string name of the connection, as defined in app/config/database.php,
* or an array containing the filename (without extension) and class name of the object,
* to be found in app/models/datasources/ or cake/libs/model/datasources/.
* @return boolean True on success, null on failure or false if the class is already loaded
* @access public
* @static
*/
Reading through the core and looking at nearly all of the helpers/plugins etc. that are available, I notice there are a lot of comments.
CakePHP is structured in such a way that it is very simple to determine where things are and what they are doing. Is it really necessary to comment all of this code? Does it make the source more messy or is it really useful? When you grok the comments, do you find them useful? Or do you even read them?
UPDATE: Here is a sample of comments taken from the CakePHP Core connection manager for example:
/**
* Loads the DataSource class for the given connection name
*
* @param mixed $connName A string name of the connection, as defined in app/config/database.php,
* or an array containing the filename (without extension) and class name of the object,
* to be found in app/models/datasources/ or cake/libs/model/datasources/.
* @return boolean True on success, null on failure or false if the class is already loaded
* @access public
* @static
*/
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（4）
这是一个 PHPDoc 注释。它对于人类和 PHPDoc 解析器来说都很有用，因为从各种源文件中获取文档注释并将它们全部编译到一个中央 HTML 文档站点中对很多程序员（包括我自己）很有帮助。
另外，虽然滚动浏览源文件很痛苦（我敢打赌，某些源文件中至少有 1/4 是文档注释），但能够一目了然地检查函数或方法的作用仍然很好，在阅读其代码时。
说到这里，现代 IDE 在其 IntelliSense 中支持文档注释，因此它们也可以解析这些注释，当您键入函数、类或方法名称时，您将能够立即看到它的作用。在这种情况下甚至不需要参考文档站点。
That's a PHPDoc comment. It's useful for both humans and PHPDoc parsers to read, because taking doc comments from various source files and compiling them all into a central HTML documentation site is helpful for a lot of programmers, including myself.
Also, while it makes it a pain to scroll through source files (I'd wager at least 1/4 of some source files are doc comments), it's still nice to be able to check at a glance what a function or method does, while reading its code.
Speaking of which, modern IDEs support doc comments in their IntelliSenses, so they can parse those too and while you're typing out a function, class or method name you'll be able to see right away what it does. There's not even a need to refer to the documentation site in this case.
好吧，就我个人而言，我不需要任何文档块注释来弄清楚发生了什么。我可以查看代码，并在几分钟内找出我需要知道的内容（假设是智能设计的代码）。所以，粗略地看去，它们确实显得多余和不必要，对吗？
错误的。为什么我必须花几分钟弄清楚一个方法的作用（确切地说，不是从高层次），以便我可以按照我需要的方式使用它？这就是文档派上用场的地方。我可以快速引用 HTML 生成的文档（直接从源代码生成）来查看我需要了解的内容，而花费的时间只需要我查看代码本身的一小部分（并且查看代码本身非常好）快的）。
现在，如果我试图突破代码应该做的事情的限制，那么是的，我可能会花更多的时间阅读代码而不是文档。但总的来说，这些文档让我更快、更容易地找到我需要的东西并继续前进。
请记住，您不需要知道一切。您只需要知道在哪里可以找到它...
哦，还有我最喜欢的另一句话，
更聪明地工作，而不是更努力...注意，这是假设相关文档已更新且编写良好。
这绝不是蛋糕特定的（我什至从未使用过蛋糕）......
Well, personally I don't need any doc-block comments to figure out what's going on. I can look at the code and in a few minutes figure out what I need to know (assuming intelligently designed code). So, from a cursory glance they do seem redundant and un-necessary, right?
Wrong. Why should I have to spend a few minutes figuring out what a method does (exactly, not from a high level) so that I can use it how I need to? That's where the documentation comes in handy. I can quickly reference a HTML generated documentation (which is generated right from the source code) to see what I need to know in a fraction of the time it would take me to look at the code itself (and looking at the code itself is pretty quick).
Now, if I am trying to push the limits of what the code was supposed to do, then yes, I may spend more time reading the code than the documentation. But in general, the docs make it MUCH faster and easier to just find what I need and move on.
Remember, you don't need to know everything. You just need to know where to find it...
Oh, and my other favorite quote,
Work Smarter, Not Harder...Note, this is assuming the documentation in question is updated and well-written.
And this is not by any means Cake specific (I have never even used Cake)...
注释，特别是在文件、类或方法级别上，对于生成文档（例如 Javadoc 或 Doxygen 之类的内容）或使用 IDE 时非常有用，可以在 IDE 中处理它们并将其显示为工具提示（将鼠标悬停在方法调用或自动完成来描述建议的方法）。
Comments, especially on a file, class, or method level are useful for either generating documentation (see things like Javadoc or Doxygen as an example) or when using an IDE, where they can be processed and displayed as a tooltip (either when hoving over a method call or in autocompletion to describe the proposed method).
评论非常有用。我发现在线 API 非常有用，因为它为我提供了我需要的任何方法和任何属性的简短摘要。 API 由使用注释块的脚本生成。 F. 前。阅读您在 API 中提到的 loadDataSource() 会更容易如果您唯一需要的是找到，而不是来自来源没有具体说明它的作用。
The comments are very useful. I find online API very useful because it gives me a brief summary on any method and any property I need. The API is generated by a script that uses the comment blocks for that. F. ex. it is much easier to read about loadDataSource() you mentioned from API than from the source if the only thin you need is to find out what it does without specifics.