PHP - Over-commenting?

Question

I recently started working on a small CMS. I usually develop .NET applications in C#, and I'm very used to commenting my fields and methods. My friend told me earler that having comments in PHP scripts is quite bad, since PHP is dynamic and parsed when requested, so having to parse the comments will take longer.

Does this statement apply to my situation, which is commenting every method and field?

Example of one of my classes:

<?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 other commenters here are exactly right regarding performance. Performance should not be a consideration when commenting in code.

However, to comment on your specific example, I believe your class does have too many comments in it. For example, take a look at this field:

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

There's a lot of "visual noise" there and the comment doesn't really explain anything anyway. You have 4 lines worth of comments that don't tell the reader any interesting details. If you want to put a comment there it should explain something interesting about the code, not just repeat what the code does. For example:

/**
 * 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 = "";

To pick on another example, take a look at this comment:

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

This comment is a good start, but it's missing some crucial information: What exactly does the show_details parameter do? What details will be missing if it is not enabled? Or what will be included when it is enabled?

Comments are not fundamentally bad, and more comments is not always worse than fewer comments. It's important to have the right comments!