2010-01-03 5 views
6

Ich habe vor kurzem angefangen, an einem kleinen CMS zu arbeiten. Ich entwickle normalerweise .NET-Anwendungen in C# und bin sehr daran gewöhnt, meine Felder und Methoden zu kommentieren. Mein Freund sagte mir früher, dass Kommentare in PHP-Skripten ziemlich schlecht sind, da PHP dynamisch ist und bei Bedarf geparst wird, so dass das Parsen der Kommentare länger dauern wird.PHP - Überschreiben?

Gilt diese Aussage für meine Situation, die jede Methode und jedes Feld kommentiert?

Beispiel einer meiner Klassen:

<?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 . "]"; 
     } 
    } 
} 
?> 
+32

Ihr Freund ist ein Idiot. –

+0

Voting zu schließen als offenkundig beleidigend, weil subjektiv und argumentativ es gerade nicht ganz schneidet. Auch die Existenz von jemandem, der so pedantisch ist, beleidigt mich. –

+0

@NSD: 2nd. Ich befürworte nicht, dass man mit dummen Dingen übermäßig kommentiert, wenn der Code für sich selbst spricht, aber die Kommentare in Ihrem Code sind in Ordnung (gut, gerade). Ärgere dich nicht über Parse-Zeiten, nicht nur mit Kommentaren, sondern auch mit kleineren Dingen. Lesbarkeit ist viel wichtiger. – mpen

Antwort

4

Sie haben kommentieren und kommentieren. Besonders Anfänger übersetzen jede einzelne Codezeile gerne in eine "menschenlesbare Sprache".

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

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

// Return y. 
return $y; 

Während Experten (bit) erfahrene Programmierer oft nur tun:

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

oder sogar

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

Unnötig zu sagen, dass der erste ist ein Beispiel für " überkommend ". Solche Kommentare können aber auch perfekt als Funktionskommentar platziert werden. Schreiben Sie einfach selbsterklärenden Code, z. Verwenden Sie keine Variablen wie $x, aber geben Sie eine Nomen Namen, wie $speed oder so und geben Sie Funktionen Verb Namen, wie increment_speed() oder so. Auf diese Weise können Sie einfach alle Kommentare innerhalb der Funktion hinterlassen, die bereits durch den Code selbst erklärt wurden.

"Over-Kommentar" jedoch nicht schädlich Auswirkungen Leistung. Es sei denn, es ist eine Zillion von Kommentarzeilen in einer einzelnen Codezeile, besonders wenn es eine Dolmetschsprache ist. Kompilierte Sprachen wie Java leiden darunter nicht; Kommentare werden bereits nach dem Kompilieren entfernt.

Aktualisieren: Sie haben ein Codebeispiel hinzugefügt; Es ist in der Tat übertrieben, private Eigenschaften zu kommentieren, besonders wenn sie bereits einen selbsterklärenden Namen haben. Die Kommentare zu den Funktionen sind in Ordnung.

+1

-1 Für die Verwendung des Wortes "Experten" – AntonioCS

+2

Huh? Tut mir leid, wenn ich dich verletzt habe. – BalusC

+1

Jeder von Ihnen gepostete Code ist "über-kommentiert"; in 'return do_stuff (" a ");" es ist blendend offensichtlich, dass du "Sachen mit einem tust, das es dann zurückbringt". Kein Kommentar ist notwendig. – DisgruntledGoat

7

Die b * llshit ist, die Menge von Kommentaren hat nichts oder nur sehr wenig mit dem tatsächlichen Bearbeitungszeiten zu tun, da die Kommentare nicht analysiert werden.

Je mehr aussagekräftige Kommentare Sie in Ihrem Code haben, desto besser wird es für den nächsten, der es pflegen muss.

Der Kommentarstil, der in Ihrem Codebeispiel dargestellt wird, ist vorbildlich, da Sie Kommentare verwenden, in denen Kommentare benötigt werden und Sie die phpdoc-Syntax verwenden, die die Erstellung von Dokumentation zum Kinderspiel macht.

Einige mögen die Kommentierung jeder Klassenvariable kritisieren, aber meiner Meinung nach ist das der Sinn der phpdoc Syntax, dass jede sinnvolle Variable, Methode und Klasse eine Erklärung hat.

+0

Ha, liebe deinen Versuch, dich selbst zu zensieren;) – DisgruntledGoat

+0

+1 phpdocs allein in manchen Fällen ist Grund genug, dies zu tun. – JasonDavis

+0

während ich nicht sagen kann, ob es für die Leistung wichtig ist, Kommentare werden von der Tokenizer wie alles andere verarbeitet – thrau

3

Hören Sie nicht auf Ihren Freund. Sie sollten sich keine Gedanken über Mikroperformance-Optimierungen machen, es sei denn, Sie haben Ihre Anwendung profiliert und festgestellt, dass sie die meiste Zeit damit zubringt, Kommentare in Ihren PHP-Dateien zu analysieren (und höchstwahrscheinlich nicht dort .... Sie benötigen viele Megabyte) Kommentare, damit es bemerkbar ist).

Es gibt viele andere Möglichkeiten, wie Sie Ihre Anwendung langsam ausführen können, z. B. falsche Datenstrukturen verwenden oder die Datenbank falsch konfigurieren. Wenn Sie alle Kommentare entfernen, werden andere Programmierer verwirrt, was dazu führt, dass die Leistung Fehler (und noch wichtiger: logische Fehler) verursacht.

10

Ihr Freund spricht Albernheit.

PHP ist dynamisch und muss Skripts wie angefordert parsen, aber die Zeit, die zum Analysieren von Kommentaren benötigt wird, ist vernachlässigbar (da es bei einem Kommentar auf die nächste relevante Zeile fällt; wahrscheinlich nur geringfügig mehr Aufwand als Leerzeichen) und der Wert der Kommentare für Sie selbst und zukünftige Betreuer des Systems ist viel, viel größer als jeder mögliche Leistungseinbruch.

Fühlen Sie sich frei, liberal zu kommentieren.

Sie können PHP mit einem Opcode-Caching-Mechanismus wie APC oder eCache jedoch erheblich beschleunigen. Investieren Sie Ihren Aufwand und Ihre Zeit in echte Lösungen wie diese, nicht die vermeintliche Albernheit, wie das Auslassen von Kommentaren.

+0

+1 für die Erwähnung APC :) – AntonioCS

+0

BTW, Opcode-Caching-Mechanismen sind toll, aber wenn Sie eine kleine Website laufen sie ' oft unnötig. Um es besser zu erklären: Eine Cache-lose Website mit 2.678.400 Seitenaufrufen pro Monat hätte im Durchschnitt eine Seitenaufrufe pro Sekunde. Die meisten kleinen Projekte werden das nicht erreichen, und die meisten ihrer Seitengenerationen werden Millisekunden benötigen. Natürlich berücksichtigt dieses Beispiel nicht die Tatsache, dass Seitenaufrufe nicht gleichmäßig verteilt sind, aber mein Punkt ist, dass die Zeit für die meisten Entwickler anderswo verbracht werden könnte. – Warty

25

Die anderen Kommentatoren hier sind hinsichtlich der Leistung genau richtig. Beim Kommentieren im Code sollte die Leistung keine Rolle spielen.

Um jedoch Ihr spezifisches Beispiel zu kommentieren, glaube ich, dass Ihre Klasse zu viele Kommentare enthält. Nehmen wir zum Beispiel einen Blick auf dieses Feld:

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

Es gibt eine Menge von „visual noise“ ist da und der Kommentar nicht wirklich sowieso nichts erklären. Sie haben Kommentare von 4 Zeilen, die dem Leser keine interessanten Details mitteilen.Wenn Sie einen Kommentar dort setzen möchten, sollte es etwas interessante über den Code erklären, nicht nur wiederholen, was der Code tut. Zum Beispiel:

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

auf ein anderes Beispiel zu wählen, werfen Sie einen Blick auf diesen Kommentar:

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

Dieser Kommentar ist ein guter Anfang, aber es wird einige wichtige Informationen fehlen: Was genau macht die show_details Parameter machen? Welche Details fehlen, wenn sie nicht aktiviert sind? Oder was wird enthalten sein, wenn es aktiviert ist?

Kommentare sind nicht grundsätzlich schlecht, und mehr Kommentare sind nicht immer schlechter als weniger Kommentare. Es ist wichtig, die richtigen Kommentare zu haben!

+4

+1 Wenn '$ username =" ";' kommentiert werden muss, muss der Leser keinen Zugriff auf die Quelle haben. – Sampson

+1

+1.Sie müssen nicht jedes Mitglied kommentieren! Wenn Sie nichts hinzufügen möchten, wie im obigen Beispiel, haben Sie keine Angst, es wegzulassen. Die offizielle Java-artige Doc-Kommentierung von "getFoo" als "Gets a foo" mit "@ this a this" und "@return that" ist wertloses visuelles Durcheinander, das es * schwerer macht * den Code IMO zu lesen. – bobince

5

Kommentieren Sie so viel wie nötig, um die Bedeutung Ihres Codes zu verdeutlichen. Die Zeit, die Sie durch das Nicht-Analysieren von Kommentaren gewinnen, wird durch den Schmerz, den undurchsichtigen Code beizubehalten, überfordert.

Das gesagt, Kommentare sollten sinnvoll sein, und Sie haben ein bisschen mehr als unbedingt notwendig. Zum Beispiel:

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

Ich Frage, ob der große Kommentar hier etwas zu Ihrem Code fügt.

3

Ich würde die Ansicht, dass ein Fall von absurderweise kontraproduktiv vorzeitiger Mikro-Optimierung:

  • die Kommentare zu ignorieren ist nur über die am wenigsten komplex und zeitraubenden Teil
  • Parsen
  • Wenn die Leistung wichtig ist, Sie Ich möchte einen Server verwenden, der den PHP-Bytecode trotzdem zwischenspeichert, wodurch der Parsing-Aufwand irrelevant wird.
  • Niemals Handel von Wartbarkeit für Leistung, außer Sie haben harte Daten, die beweisen, dass Sie ein Leistungsproblem haben und wo genau es liegt
0

Wenn Leistung eine Priorität für Ihre PHP-Code ist, sollten Sie einen Bytecode Cache verwenden wie:

Bytecode speichert Geschäftscode, der analysiert und in Bytecode kompiliert wurde. Die nachfolgende Ausführung derselben PHP-Seite muss den Code nicht analysieren, geschweige denn die Kommentare.

Daher beeinträchtigen Code-Kommentare die Leistung nur in Anwendungsbereitstellungen, bei denen die Leistung nicht wichtig ist.

Verwandte Themen