Dokumentation oder Aneinander vorbei reden

Wie wichtig die Dokumentation von Software und Webapps ist zeigt sich meist erst, wenn es zu spät ist. Ein anderer Programmierer muss am alten Projekt arbeiten oder man selbst versteht den eigenen Code schon nach kurzer Zeit nicht mehr.

„Dokumentieren? Kommentare brauch ich nicht, ist doch klar was passiert.“ Und nach 2 Monaten kommt der große Schreck. Um ein Produkt gut verwenden zu können, muss es leicht verwendbar sein. Dazu gehört eben auch die Verfügbarkeit von Erklärungen. Das kann man selbst erledigen, aber wer will schon alle paar Tage gefragt werden, was Zeile XY in Dokument ABC bedeutet?

Oder wir dokumentieren unseren Code. Und warum? Damit nicht nur andere es verstehen und benutzen können, sondern auch man selbst. Benutzt du gern Bibliotheken oder Komponenten anderer ohne jegliche Kommentare? Nein. Und das gleiche sollte für deinen Code gelten.

Und was soll ich kommentieren?

Zum einen sind das Kommentare, die die Entwicklung wiederspiegeln, also Dinge wie

  • Dateiname
  • Versionsnummer
  • Erstellungsdatum
  • Datum der letzten Änderung
  • Zweck des Dokuments
  • Abhängigkeiten im gesamten Projekt

Diese dokumentarischen Kommentare dienen lediglich der Zuordnung.
Eine weitere Kategorie betreffen den Entwicklungsprozess und dienen der Kommunikation unter den Programmieren, man nennt sie funktionale Kommentare. Meist sind es TO DOs aber auch andere Kommentare wie Fehlerbeschreibungen oder Anmerkungen über potentielle Verbesserungen:

  • TO DOs
  • Fehlerbeschreibungen
  • Anmerkungen über potentielle Verbesserungen

Um die Arbeit mit diesen Kommentare zu erleichtern, lohnt es sich eine einheitliche Formatierung wie z.B. „TO DO“ oder „to do“ zu benutzen, dank der man dann im Editor die betreffenden Zeilen suchen und bearbeiten kann.

Die wichtigsten Kommentare sind jedoch die, die erklären, wie etwas funktioniert: erklärende Kommentare also.

        //pear klasse einbinden
        require_once 'Contact_Vcard_Parse.php';
        
        //parser instanziieren
        $parser = new Contact_Vcard_Parse();

Wie kommentiere ich?

In PHP zum Beispiel haben wir mehrere Möglichkeiten zu kommentieren. Einmal über einzeilige Kommentare:

  <?php
    print "foo"; // Dies ist ein einzeiliger Kommentar
  ?>

oder durch mehrzeilige Kommentare:

  <?php
    print "foo";
    /**
    * dies ist ein mehrzeiliger
    * Kommentar
    */
  ?>

Eine Erweiterung sind Code-Dokumentiertools wie PHPDoc, die mehrzeilige Kommentare parsen können, um aus diesen Kommentaren automatisch eine Sourcedokumentation zu erstellen. Diese Kommentare werden statt mit /* mit /** gestartet und haben in jeder neuen Zeile ein Stern:

/**
 * Kurze Beschreibung - Wird im Index benutzt
 *
 * Doc-Comments beginnen mit einem Slash (/) gefolgt von zwei Sternchen.
 * Sie enden, wie von Javadoc gewohnt, mit Sternchen (*) und Slash (/).
 * Die Kommentare stehen vor PHP Schlüsselwörtern und
 * enthalten Dokumentationstags.
 * 
 */
 function foo() {
   print "API Dokumentation in Java und dem 'PHP Extension and Add-On Repository' PEAR.";
 } 

Eine Übersicht zur Dokumentation in PHP5 inkl. Beispielen findet ihr in Sebastian Bergmans Online-Buch „Professionelle Softwareentwicklung mit PHP 5“: Kapitel 13. Code-Dokumentation

So, jetzt an die Arbeit!

Ein Gedanke zu „Dokumentation oder Aneinander vorbei reden“

  1. Ich empfehle für grosse Projekte noch einen Schritt weiter zu gehen. Mit PHPDocumentor (www.phpdoc.org) lassen sich Projekte wunderschön dokumentieren und viele Editoren bieten dann Code-Assist auf die eigenen Funktionen.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.