CakePHP代码中的注释是否真的使用/必要？

Question

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

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

Answer 1

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

此外,虽然滚动浏览源文件很麻烦(我下注至少有1/4的源文件是文档注释)但是能够一目了然地查看函数或方法的功能仍然很好,在阅读其代码时.

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