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

Es lässt sich festgehalten, dass eine gut durchdachte, standardisierte und konsequent durchgeührte Kommentierung für jedes Projekt und deren Mitarbeiter einen erheblichen Mehrwert darstellen können.

Getagged mit: , , ,
Veröffentlicht unter Entwicklung
5 Kommentar auf “Richtig kommentieren in PHP
  1. Daniel sagt:

    Abgesehen davon, dass der Code lesbarer wird und man automatisch Dokumentationen erstellen kann hilft einem auch die IDE (z.B. Netbeans) viel weiter, wenn sie anhand der Kommentare weiß mit welchem Typ wir gerade arbeiten. Auch beim Kommentieren selbst nimmt die IDE einem oft viel Arbeit ab. Methode schreiben, DocBlock erstellen und die Annotations werden automatisch erzeugt und müssen nur noch etwas angepasst werden.

  2. Tom Thaler sagt:

    Das ist absolut richtig. Auch Eclipse bietet diese Funktionalitäten, sodass die Struktur der Kommentare automatisch an den richtigen Stellen erzeugt werden. Schön ist hier außerdem, dass der individuelle Aufbau der Kommentare als Templates abgelegt, exportiert und importiert werden kann, was es innerhalb von Projekten sehr komfortabel macht, die Kommentierung einheitlich zu gestalten.

  3. timwebdev sagt:

    Sehr wichtiger Post, gute und richtige Kommentierung ist einfach nötig! Gerade die PHPDoc-Kommentare gehören einfach in den Quellcode, wie das Amen in die Kirche. Ich verstehe nicht, wie einige Entwickler diese einfache Arbeitsweise ignorieren können. Wie schon erwähnt müssen weitere Stellen im Code kommentiert sein und dafür reicht der Kommentarkopf einfach nicht aus. Man sollte nur Teile kommentieren die nötig sind, aber generell gilt, lieber zu viel als zu wenig. Desweitern stellt sich – abgesehen von der PHPDoc-Syntax – auch die Frage, warum nicht einfach mal auf deutsch (http://web.archive.org/web/20110721135221/http://www.phphatesme.com/blog/softwaretechnik/was-ware-wenn-einfach-mal-auf-deutsch/) kommentieren?

    Btw: Zeile 23, $this->autoFaehrt

  4. Tom Thaler sagt:

    Das ist wirklich ein sehr interessanter Beitrag. Wenn ich zitieren darf: “Mein Englisch ist gut, aber mein Deutsch ist besser.” Das sehe ich genauso. Ich denke man sollte auch hier eine Entscheidung auf Basis des Projekts herbeiführen. Wenn es sich um rein interne Projekte, an denen nur deutschsprachige Kollegen beteiligt sind, sehe ich keine Grund englisch zu kommentieren. Ich selbst kommentieren in entsprechenden Firmenprojekten ausschließlich auf deutsch, lediglich bei den Variablennamen halte ich mich im Allgemeinen an die “eiserne Regel”.

  5. Micha sagt:

    Netter Blog, gefaellt mir sehr gut. Auch gute Themen.