PHP: Richtig dokumentieren

Kommentare helfen, den Programmcode besser zu verstehen. Und noch besser geht es, wenn Sie spezielle Kommentar-Tags und den PHP-Documentor einsetzen. Der folgende Beitrag zeigt, wie es geht.

Je umfangreicher ein Projekt wird, desto wichtiger wird die Dokumentation. Eine Klassen- oder Funktions-Bibliothek wächst mit der Zeit so stark an, dass selbst der Programmierer nicht mehr durchblickt, welche Funktion wofür vorgesehen ist und welche Parameter sie verlangt. Um sich stundenlanges Wühlen im Code und das erneute Studieren der

Funktion oder Klasse zu ersparen, sollten Sie den Code von Anfang an dokumentieren. Dazu setzen Sie vor jede Klasse, Methode oder Funktion einen Kommentar-Header, in dem steht,

– welche Aufgabe die Funktion hat

– welche Parameter sie erwartet

– welchen Datentyp sie zurückgibt

Am besten funktioniert das Dokumentieren wenn Sie sich an einen Standard halten, den der PHP-Documentor vorgibt und der sich an ähnliche Dokumentations-Standards wie Javadoc anlehnt. Demnach sieht ein Kommentargerüst so aus:

/**

* Hier der Kommentar

*/

Einen Kommentarblock schreiben Sie direkt vor die Klasse oder Funktion. In der ersten Zeile steht die Funktions- oder Klassenbeschreibung. Nach einer Leerzeile können Sie eine ausführlichere Erläuterung hinzufügen, etwa

/**

* Testklasse

*

* Gibt den an den Konstruktor übergebenen Text

* über die Methode output() wieder zurück

*/

Wichtig: Jede neue Zeile muss mit * beginnen – auch die Leerzeile. Zusätzlich zu den Beschreibungen bietet PHP-Documentor eigene Tags. Das sind spezielle Auszeichnungen, um auf Variablen oder Rückgabewerte hinzuweisen. Ein Beispiel:

/**

* Datum eines Eintrags zurückgeben

*

* @param int $id ID des Datenbankeintrages

* @return string

*/

Innerhalb eines solchen Blocks können Sie auch HTML verwenden, etwa, um ein Code-Beispiel zu geben:

/**

* Konstruktor

*

* Weist den Klassenvariablen die Parameter zu

* <code>

* $oTest = new cTest(‚Testnachricht‘);

* </code>

* @param string $argStrMessage Nachrichteninhalt

* @return void

*/

In der Dokumentation von PHP-Documentor finden Sie noch eine Menge weiterer Tags und viele Anwendungsbeispiele. Viele Editoren, etwa Eclipse, unterstützen die Dokumentation, indem Sie bei der Eingabe von /** automatisch schon ein Kommentargerüst erzeugt. Außerdem gibt es bei Eclipse und auch bei Zend Autoergänzungs-Code für die Kommentar-Tags.

Dokumentation automatisch erzeugen

Das Erzeugen der fertigen Dokumentation übernimmt der PHP-Documentor. Dieses PHP-Programmpaket installieren Sie auf Ihrem Entwicklungssystem. Dazu holen Sie sich das ZIP-Archiv von http://www.phpdoc.org/downloads.php und entpacken es in ein Verzeichnis auf Ihrem Entwicklungs-Webserver. Danach starten Sie den PHP-Documentor mit der Eingabe

http://ihretestdomain/pfadzumdokumentor/phpdoc.php.




In dem danach erscheinenden Eingabeformular geben Sie in Target das Zielverzeichnis für die Dokumentation ein. Unter Files to parse oder Directory to parse schreiben Sie die Datei oder den Ordner mit den zu parsenden Programm-Files. Sind alle Einstellungen fertig, klicken Sie auf Send form. Danach öffnen Sie den zuvor festgelegten Zielordner und darin die Datei index.html. Fertig ist die erste Test-Dokumentation.

Kommentieren mit Bedacht

Kommentare sind sinnvoll. Allerdings nur dann, wenn sie mit Bedacht eingesetzt werden. Denn Kommentare können, übertrieben eingesetzt, den Blick auf den Quelltext und die Zusammenhänge versperren. Das ist etwa dann der Fall, wenn vor jeder Zeile Quelltext ein Kommentar steht.

Gehen Sie von dem Grundsatz aus: Guter Quelltext ist auch ohne Kommentare lesbar. Natürlich muss Ihr Quellcode auch entsprechend gut aussehen, also mit beschreibenden Namen für Variablen, Funktionen, Klassen und so weiter arbeiten.

Schreiben Sie einen Kommentar innerhalb von Klassen, Methoden und Funktionen nur dort, wo er wirklich sinnvoll ist – etwa bei einem raffinierten Algorithmus, den Sie sich selbst und anderen erklären müssen. Aber überlegen Sie, ob Sie diese Dokumentation nicht auch in den Kommentarblock vor die Funktion schreiben und ihn dort mit einem Code-Beispiel erklären könnten. Dann bleibt der eigentliche Quelltext sauber und Sie haben die Erklärung später auch in der Dokumentation.

Code einrücken

Entscheidend für die Lesbarkeit von Code ist, ihn sauber zu strukturieren. Nutzen Sie deshalb Einrückungen, um logische Zusammenhänge gleich sichtbar zu machen. Nach jedem if und jedem Schleifenbeginn sollten Sie die nächste Zeile mit der Tabulatortaste einrücken und erst dann schreiben.

Ist das Konstrukt zu Ende, setzen Sie den Cursor wieder um eine Tabulatorstelle weiter nach vorne. Wenn Sie gemeinsam mit anderen Nutzern arbeiten, einigen Sie sich auf einen gemeinsamen Formatierungsstandard, zum Beispiel darauf, ob nach einem if die geschweifte Klammer noch in derselben Zeile steht oder eine darunter.

Ähnliche Beiträge