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 回答