代码之家 › 专栏 › 技术社区 › Chuck Burgess

CakePHP代码中的注释真的被使用了/必要吗?

cakephp-1.2 cakephp-1.3 cakephp php

0

Chuck Burgess · 技术社区 · 14 年前

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

更新:以下是从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
 */

4 回复 | 直到 12 年前

1

9

BoltClock 14 年前

那是个好主意 PHPDoc 二者都 人类和PHPDoc解析器需要阅读,因为从各种源文件中获取文档注释并将它们全部编译到一个中心HTML文档站点对很多程序员都有帮助,包括我自己。

另外,虽然滚动源文件会让人很痛苦(我敢打赌,至少有1/4的源文件是doc注释),但在阅读代码时,能够一目了然地检查函数或方法的功能还是不错的。

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

2

4

ircmaxell 14 年前

需要任何文档块注释来找出发生了什么。我可以看一下代码,在几分钟内弄清楚我需要知道什么(假设代码是智能设计的)。所以,粗略一看,它们确实显得多余和不必要,对吧?

错了。为什么我要花几分钟弄清楚一个方法是做什么的(确切地说,不是从一个高层次上),这样我就可以按我需要的方式使用它?这就是文档的用武之地。我可以快速地引用一个HTML生成的文档(它是从源代码生成的)来查看我需要知道的内容,只需花一小部分时间来查看代码本身(而且查看代码本身非常快)。

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

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

而且这绝对不是蛋糕特有的(我从来没有用过蛋糕)。。。

3

4

Thomas Owens 14 年前

注释,尤其是文件、类或方法级别的注释,对于生成文档(以Javadoc或Doxygen为例)或在使用IDE时非常有用,在IDE中,注释可以作为工具提示进行处理和显示(在跳过方法调用或在自动完成中描述所建议的方法时)。

4

0

bancer 14 年前

这些评论很有用。我发现在线API非常有用,因为它给了我一个关于任何方法和我需要的任何属性的简要总结。API是由使用注释块的脚本生成的。它更容易阅读 loadDataSource() 你从API提到的 source 如果你唯一需要的是找出它的作用没有细节。