PHP - 过度评论？

我最近开始在一个小型CMS上工作.我通常用C#开发.NET应用程序,而且我习惯于评论我的字段和方法.我的朋友告诉我,在PHP脚本中有注释是非常糟糕的,因为PHP是动态的并且在被请求时被解析,因此必须解析注释需要更长时间.

这个陈述是否适用于我的情况,即对每个方法和字段进行评论？

我的一个课程示例:

.
*/

/**
 * Controls database connections.
 *
 * @author AJ Ravindiran
 * @version 1.0.0 Jan-02-2010
 */
class database {
    /**
     * The database connection ip address.
     * @var string
     */
    private $host = "";

    /**
     * The database user's name.
     * @var string
     */
    private $username = "";
    /**
     * The database user's password.
     * @var string
     */
    private $password = "";

    /**
     * The database that this instance will write to, and read from.
     * @var string
     */
    private $database = "";

    /**
     * Holds the mysql connection instance.
     * @var resource
     */
    private $connection = null;

    /**
     * Whether the instance is connected to the specified database.
     * @var bool
     */
    private $connected = false;

    /**
     * Constructs a new database instance.
     * @param string $host The database server host.
     * @param string $port The database server port.
     * @param string $username The database's username authentication.
     * @param string $password The username's specified password.
     */
    public function __construct($host = "localhost", $username = "root", $password = "") {
        $this->host = $host;
        $this->username = $username;
        $this->password = $password;
    }

    /**
     * Connects to the given database.
     * @param string $database
     */
    public function connect($database) {
        $this->database = $database;

        // TODO: handle errors.
        $this->connection = @mysql_connect($this->host, $this->username, $this->password) or die();
        @mysql_select_db($this->database, $this->connection) or die();

        /*
         * If the connection was successful, we can now
         * identify that the connection is sustained.
         */
        if ($this->connect != null) {
            $this->connected = true;
        }
    }

    /**
     * Gets the specified connection details from this instance.
     * @param boolean $show_details
     * @return string The connection string.
     */
    public function getConnectionString($show_details = false) {
        if ($show_details) {
            return "database[host=" . $this->host 
                    . ", port=" . $this->port
                    . ", user=" . $this->username
                    . ", pass=" . $this->password
                    . ", database=" . $this->database . "]";
        } else {
            return "database[host=" . $this->host
                    . ", port=" . $this->port . "]";
        }
    }
}
?>

Eilon.. 25

这里的其他评论者对于表现完全正确.在代码中进行注释时,不应考虑性能.

但是,为了评论您的具体示例,我相信您的课程中有太多评论.例如,看看这个字段:

/**
 * The database user's name.
 * @var string
 */
private $username = "";

那里有很多"视觉噪音",评论并没有真正解释任何事情.你有4行评论,不会告诉读者任何有趣的细节.如果你想在那里发表评论,它应该解释一些关于代码的有趣内容,而不仅仅是重复代码的作用.例如:

/**
 * The database user's name. This field has to be 5 to 10 characters long. It
 * is not required if the connection security is disabled.
 * @var string
 */
private $username = "";

要选择其他示例,请查看此评论:

/** 
 * Gets the specified connection details from this instance. 
 * @param boolean $show_details 
 * @return string The connection string. 
 */
public function getConnectionString($show_details = false) {
    ...

这个评论是一个良好的开端,但它缺少一些关键信息:show_details参数究竟做了什么？如果未启用,将丢失哪些详细信息？或者当它究竟会被列入被启用？

评论并非根本不好,更多评论并不总是比评论更少.拥有正确的评论非常重要!

这里的其他评论者对于表现完全正确.在代码中进行注释时,不应考虑性能.

但是,为了评论您的具体示例,我相信您的课程中有太多评论.例如,看看这个字段:

/**
 * The database user's name.
 * @var string
 */
private $username = "";

那里有很多"视觉噪音",评论并没有真正解释任何事情.你有4行评论,不会告诉读者任何有趣的细节.如果你想在那里发表评论,它应该解释一些关于代码的有趣内容,而不仅仅是重复代码的作用.例如:

/**
 * The database user's name. This field has to be 5 to 10 characters long. It
 * is not required if the connection security is disabled.
 * @var string
 */
private $username = "";

要选择其他示例,请查看此评论:

/** 
 * Gets the specified connection details from this instance. 
 * @param boolean $show_details 
 * @return string The connection string. 
 */
public function getConnectionString($show_details = false) {
    ...

这个评论是一个良好的开端,但它缺少一些关键信息:show_details参数究竟做了什么？如果未启用,将丢失哪些详细信息？或者当它究竟会被列入被启用？

评论并非根本不好,更多评论并不总是比评论更少.拥有正确的评论非常重要!

你的朋友说傻.

PHP是动态的,必须按照请求解析脚本,但是解析注释所花费的时间可以忽略不计(因为只要它遇到注释就会丢弃到下一个相关行;它可能只是略微超过空白的开销)和值对自己和系统未来维护者的评论远远超过任何潜在的性能影响.

随意评论.

但是,通过使用像APC或eCache这样的操作码缓存机制,可以大大加快PHP的速度.把你的努力和时间投入到这样的真实解决方案中,而不是假设愚蠢,比如省略评论.

那是b*llshit,评论的数量与实际处理时间没有任何关系,也没有什么关系,因为评论没有被解析.

您在代码中的注释越有意义,对于下一个必须维护它的人来说就越好.

代码示例中显示的注释样式是示例性的,因为您正在使用需要注释的注释,并且您正在使用phpdoc语法,这将使文档创建变得轻而易举.

有些人可能会批评每个类变量的注释,但在我看来,使用phpdoc语法就是每个有意义的变量,方法和类都有一个解释.

尽可能多地评论,以明确代码的含义.通过不解析注释获得的时间(如果有的话)被维护不透明代码的痛苦所淹没.

也就是说,评论应该是有意义的,而且你需要的不仅仅是必要的.例如:

/**
 * The database that this instance will write to, and read from.
 * @var string
 */
private $database = "";

我怀疑这里的大评论是否会为您的代码添加任何内容.