Richtig kommentieren in PHP

Die Quellcode-Kommentierung ist bei der Entwicklung nach wie vor ein eher belächeltes Thema, unabhängig von der Programmiersprache. Ein gute Kommentierung hilft allerdings nicht nur anderen Entwicklern, den Code besser zu verstehen, sondern es lassen sich beispielsweise auch Dokumentation erstellen, ohne das man bei der Entwicklung einen wesentlichen Mehraufwand hat. Außerdem wird durch eine richtige Kommentierung die Lesbarkeit des Codes enorm erhöht. Doch wie kommentiert man eigentlich “richtig” in PHP?

Zur Beantwortung dieser Frage sollte man zunächst Ziele definieren, welche mit der Kommentierung erreicht werden sollen. Diese könnten in den meisten Projekten wie folgt aussehen:

1. Automatische Generierung einer Dokumentation
2. Besseres Verständnis des Codes für andere Entwickler
3. Möglichst geringer Aufwand

Die Automatische Generierung einer Dokumentation kann in PHP mit den Tool PHPDoc erreicht werden, welches über die Kommandozeile mit dem PEAR-Installer installiert werden kann:

pear upgrade PhpDocumentor

Das bessere Verständnis ergibt sich einerseits aus der Kommentierung selbst, andererseits durch die Position und den Aufbau der Kommentare. Unter möglichst geringem Aufwand könnte man verstehen, dass man nur die “wichtigen” Kommentare erfasst. Die Wichtigkeit von Informationen sollte dabei je nach Projekt entschieden werden. Bei der objektorientierten Programmierung mit PHP sollten in jedem Fall alle Klassen und Funktionen kommentiert werden, wobei durchaus unterschiedliche Informationen festgehalten werden sollten. Beispielsweise ist es sinnvoll die Versionangabe im Klassenkommentar, und nicht in jeder einzelnen Methode festzuhalten.

Folgende Informationen erscheinen deshalb in den meisten Projekten sinnvoll:

Klassen

• Beschreibung: Was repräsentiert die Klasse und wofür sollte die verwendet werden?
• Kategorie, also beispielsweise Daten, Programmlogik oder Schnittstelle
• Version
• Autor

Funktionen

• Beschreibung: Was tut die Funktion und wofür sollte sie verwendet werden?
• Parameter: Name, Typ und Beschreibung der zu übergebenden Parameter
• Return: Was gibt die Funktion zurück
• Ggf. Verbesserungsvorschläge

Damit diese Informationen in einer Dokumentation korrekt erfasst werden können, müssen die Kommentare bestimmten Konventionen genügen. Diese Konventionen können im Falle von PHPDoc hier nachgeschlagen werden. Die Umsetzung der Anforderungen könnte dann beispielhaft wie folgt aussehen:

/**
* Diese Klasse repräsentiert ein Auto.
*
* @author   Tom Thaler
* @version  1.0
* @category Logik
*/
class Auto {
   public $gang = null;
   public $gasGedrueckt = false;
   public $bremseGedrueckt = true;
   public $kupplungGedrueckt = true;
   public $autoFaehrt = false;

   /**
    * Anfahren mit dem aktuellen Auto
    *
    * @param int $gang Der Gang, in dem angefahren werden soll (1-5)
    * @todo Die Kupplung darf nicht einfach losgelassen werden!
    *
    * @return bool
    */

   public function anfahren($gang) {
      if ( $autoFaehrt ) {
         return false;
      } else {
         $this->gang = $gang;
         $this->bremsGedrueckt = false;
         $this->gasGedrueckt = true;
         $this->kupplungGedrueckt = false;
         return $this->autoFaehrt = true;
      }
   }

   /**
    * Stoppt das aktuelle Auto
    *
    * @return true
    */
   public function anhalten() {
      ...
   }
}

Natürlich ist es darüber hinaus sinnvoll an komplizierteren Stellen im Code kurze Kommentare zu hinterlassen, welche dann allerdings nicht in der Dokumentation erscheinen. Mit PHPDoc lässt sich anschließend eine komplette Dokumentation des Projektes und aller enthaltenen Dateien und Klassen wie folgt erzeugen.

phpdoc -d /pfad/zum/project -f /pfad/zum/target