通过阅读核心并查看几乎所有可用的助手/插件等，我注意到有很多评论。
CakePHP的结构使得确定事物的位置和所做的事情变得非常简单。是否真的有必要对所有这些代码进行评论？它会使源更混乱还是真的有用？当您查看评论时，您觉得它们有用吗？或者你甚至读过它们？
更新：以下是从CakePHP核心连接管理器获取的注释示例，例如：
/**
* 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
*/
答案 0 :(得分：9)
这是PHPDoc评论。它对人类和PHPDoc解析器的读取非常有用，因为从各种源文件中获取doc注释并将它们全部编译到一个中央HTML文档站点对很多程序员都有帮助，包括我自己。
另外，虽然滚动浏览源文件很麻烦（我下注至少1/4的一些源文件是文档注释）但是能够一目了然地检查一下函数是什么还是很好的。方法确实在阅读其代码时。
说到现代IDE，它们在IntelliSenses中支持doc注释，因此他们也可以解析这些注释，当你输入一个函数，类或方法名称时，你将能够立即看到它的作用。在这种情况下甚至不需要参考文档站点。
答案 1 :(得分：4)
嗯，我个人并不需要任何文档块评论来弄清楚发生了什么。我可以查看代码，并在几分钟内找出我需要知道的内容（假设智能设计的代码）。所以，从粗略的一瞥看，它们似乎是多余的，不必要的，对吗？
错误。为什么我要花几分钟搞清楚方法的作用（确切地说，不是从高级别开始），以便我可以使用它我需要的方式？这就是文档派上用场的地方。我可以快速引用HTML生成的文档（直接从源代码生成），看看我需要知道的东西，只需要花一点时间来查看代码本身（并且查看代码本身很漂亮）快）。
现在，如果我试图突破代码应该做的限制，那么是的，我可能会花更多时间阅读代码而不是文档。但总的来说，文档使得我更快更容易找到我需要的东西并继续前进。
记住，你不需要知道一切。你只需要知道在哪里找到它......
哦，我最喜欢的另一句话，Work Smarter, Not Harder ......
请注意，这是假设有问题的文档已更新并且写得很好。
这绝不是特定于Cake的（我从未使用过Cake）......
答案 2 :(得分：4)
注释，特别是文件，类或方法级别的注释对于生成文档（例如Javadoc或Doxygen之类的东西）或使用IDE时都很有用，它们可以作为工具提示进行处理和显示（或者当通过方法调用或自动完成来描述所提出的方法时。）
答案 3 :(得分：0)
评论非常有用。我发现在线API非常有用，因为它给出了我需要的任何方法和任何属性的简短摘要。 API由脚本生成，该脚本使用注释块。 F.前。如果你需要的只是找到它没有具体的内容，那么你可以更容易地阅读你在API中提到的loadDataSource()而不是source。