0

阅读核心并查看几乎所有可用的帮助程序/插件等,我注意到有很多评论。

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
 */
4

4 回答 4

9

那是一个PHPDoc注释。它对人类和 PHPDoc 解析器非常有用,因为从各种源文件中获取文档注释并将它们全部编译到一个中央 HTML 文档站点对很多程序员都有帮助,包括我自己。

此外,虽然滚动浏览源文件很痛苦(我敢打赌,一些源文件中至少有 1/4 是文档注释),但能够一目了然地检查函数或方法的作用仍然很好,在阅读其代码时。

说到这一点,现代 IDE 在其 IntelliSense 中支持文档注释,因此它们也可以解析这些注释,当您输入函数、类或方法名称时,您将能够立即看到它的作用。在这种情况下,甚至不需要参考文档站点。

于 2010-08-27T16:28:51.933 回答
4

好吧,就我个人而言,我不需要任何文档块评论来弄清楚发生了什么。我可以查看代码并在几分钟内找出我需要知道的内容(假设代码是智能设计的)。所以,粗略一看,它们确实是多余的和不必要的,对吧?

错误的。为什么我必须花几分钟弄清楚一个方法的作用(确切地说,不是从高层次),以便我可以按需要使用它?这就是文档派上用场的地方。我可以快速参考 HTML 生成的文档(直接从源代码生成)来查看我需要知道的内容,而这只是我查看代码本身所需的一小部分时间(并且查看代码本身很漂亮快的)。

现在,如果我试图突破代码应该做的限制,那么是的,我可能会花更多的时间阅读代码而不是文档。但总的来说,这些文档让我更快、更容易地找到我需要的东西并继续前进。

请记住,您不需要知道所有事情。你只需要知道在哪里可以找到它...

哦,还有我最喜欢的一句话,Work Smarter, Not Harder...

请注意,这是假设相关文档已更新且编写良好。

这绝不是特定于蛋糕的(我什至从未使用过蛋糕)......

于 2010-08-27T16:04:17.227 回答
4

注释,尤其是在文件、类或方法级别上的注释对于生成文档(参见 Javadoc 或 Doxygen 之类的示例)或在使用 IDE 时非常有用,它们可以在其中被处理并显示为工具提示(在悬停时)方法调用或在自动完成中描述建议的方法)。

于 2010-08-27T16:27:51.523 回答
0

评论非常有用。我发现在线 API 非常有用,因为它为我提供了我需要的任何方法和任何属性的简要总结。API 由使用注释块的脚本生成。前。如果您唯一需要的是在没有细节的情况下找出它的作用,那么从 API 中阅读您提到的loadDataSource()比从源代码中阅读要容易得多。

于 2010-08-27T18:20:59.497 回答