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

You have commenting and commenting. Especially starters like to translate every single line of code into a “human readable language”.

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

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

// Return y.
return $y;

While experts (bit) more experienced programmers often just do:

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

or even

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

Needless to say that the first is an example of “over-commenting”. Those kind of comments can however also perfectly be placed as a function-comment. Just write self-explaining code, e.g. do not use variables like $x, but give it a noun name, like $speed or so and give functions a verb name, like increment_speed() or so. This way you can just leave all comments inside the function away which are already explained by the code itself.

“Over-commenting” however doesn’t harmfully impact performance. Unless it’s a zillion of comment lines on a single line of code, especially if it is an interpreting language. Compiled languages such as Java doesn’t suffer from this; comments are already removed after compilation.

Update: you included a code example; it is indeed overdone to comment private properties, especially if they already have a self-explaining name. The comments on the functions are okay.