PHP - 过度评论？

Question

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

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

我的一个课程示例:

<?php
/* 
 *     jWeb
 *     Copyright (C) 2010 AJ Ravindiran
 * 
 *     This program is free software: you can redistribute it and/or modify
 *     it under the terms of the GNU General Public License as published by
 *     the Free Software Foundation, either version 3 of the License, or
 *     (at your option) any later version.
 * 
 *     This program is distributed in the hope that it will be useful,
 *     but WITHOUT ANY WARRANTY; without even the implied warranty of
 *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *     GNU General Public License for more details.
 * 
 *     You should have received a copy of the GNU General Public License
 *     along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * 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 . "]";
        }
    }
}
?>

Answer 1

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

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

/**
 * 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参数究竟做了什么？如果未启用,将丢失哪些详细信息？或者当它究竟会被列入被启用？

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

Answer 2

你的朋友说傻.

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

随意评论.

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

Answer 3

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

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

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

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

Answer 4

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

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

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

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

Answer 5

你有评论也有评论。尤其是初学者喜欢将每一行代码翻译成“人类可读的语言”。

// Assign "a" to x.
$x = "a";

// Do stuff with x and get y.
$y = do_stuff($x);

// Return y.
return $y;

虽然专家 （位）更有经验的程序员通常只是这样做：

// Do stuff with "a" and return it.
$x = "a";
$y = do_stuff($x);
return $y;

甚至

// Do stuff with "a" and return it.
return do_stuff("a");

不用说，第一个就是“过度评论”的例子。然而，这些类型的注释也可以完美地作为函数注释放置。只需编写自我解释的代码，例如，不要使用变量，如$x，而是给它一个名词名称，如$speed或 so，并为函数提供一个动词名称，如increment_speed()或 so。这样你就可以保留函数内的所有注释，这些注释已经由代码本身解释了。

然而，“过度评论”不会对性能产生有害影响。除非它是单行代码上的无数注释行，特别是如果它是一种解释性语言。像 Java 这样的编译语言不会受到这个问题的影响。编译后注释已被删除。

更新：您包含了一个代码示例；评论私有财产确实有些过头了，尤其是如果它们已经有了一个不言自明的名字的话。功能上的注释还可以。