6
Recientemente comencé a trabajar en un pequeño CMS. Usualmente desarrollo aplicaciones .NET en C#, y estoy muy acostumbrado a comentar mis campos y métodos. Mi amigo me dijo Earler que tener comentarios en scripts PHP es bastante malo, ya que PHP es dinámico y se analiza cuando se solicita, por lo que tener que analizar los comentarios tomará más tiempo.PHP - ¿Haciendo un comentario excesivo?
¿Se aplica esta afirmación a mi situación, que es comentar cada método y campo?
Ejemplo de una de mis clases:
<?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 . "]";
}
}
}
?>
Tu amigo es un idiota. –
Votar para cerrar como descaradamente ofensivo porque subjetivo y argumentativo simplemente no acaba de cortarlo. Además, la existencia de alguien que es tan pedante me ofende. –
@NSD: 2nded. No apoyo el exceso de comentarios con cosas estúpidas cuando el código habla por sí mismo, pero los comentarios en su código están bien (bien, incluso). No te preocupes por los tiempos de análisis, no solo con comentarios, sino algo menor como eso. La legibilidad es mucho más importante. – mpen