PHP: Dokumentieren mit Php-Documentor

Das war eine lange Nacht gestern. Bis kurz vor zwölf habe ich dokumentiert. So lange habe ich mich noch nie mit Kommentarzeilen beschäftigt. Komisch. Woher kommt diese plötzliche Lust, den Code zu erklären? Die Antwort heißt phpDocumentor.

Wenn eines nicht im Wesen des Programmierers liegt, dann ist es das Dokumentieren von Software. Denn was ist daran interessant? Wo liegt die Herausforderung? Schließlich ist das Programmier-Problem gelöst, der Algorithmus sitzt und die Software ist online.

Der Katzenjammer kommt zwei Wochen später wenn man den zuvor noch so genialen Algorithmus nachvollziehen möchte. Ohne die Anmerkungen ist nichts mehr zu verstehen. Aber diese Erfahrung macht man nur einmal. Danach wird jeder Kommentare in seinem PHP-Code hinterlassen.

Doch auch die kleinen Anmerkungen nutzen nicht mehr viel, wenn aus der einst einzelnen PHP-Datei eine dicke Web-Anwendung mit 20 oder 50 Dateien geworden ist. Dann verlagert sich das Problem von “was macht diese Code-Zeile?” in Richtung “wo steckt diese Funktion und wozu ist sie überhaupt da?”. Noch kniffliger wird es beim objektorientierten Programmieren: Wohin gehört diese Funktion, wovon hängt die Klasse da ab und was zum Donner hat sie in dieser Datei zu suchen?”

Einfache Syntax

Die Lösung des Problems ist einfach. Gewöhnen Sie sich eine bestimmte Syntax für das Dokumentieren an und lassen Sie phpDocumentor den Rest erledigen.

Das Open Source Dokumentations-System sammelt innerhalb eines Unterverzeichnisses sämtliche PHP-Dateien ein und durchsucht sie nach Klassen, Funktionen und Kommentaren. Schon eine Anwendung des Programms ohne speziell angepasste Kommentare bringt eine brauchbare Übersicht der in einem Programmierprojekt enthaltenen Klassen und Funktionen.

Richtig brauchbar wird phpDocumentor aber erst, wenn Sie die Kommentare anpassen. Das Grundprinzip ist einfach. Kommentare für den Documentor werden immer mit /** eingeleitet. Vor jeder Kommentarzeile steht ein *, den Abschluss bildet */. Ein Beispiel:

/**

* Ein Kommentartext

*/

Dieser Kommentar wird immer der nächst folgenden Funktion, Klasse oder Variablen zugeordnet. Bei Variablen innerhalb von Klassen kann der Documentor noch eine Arbeit übernehmen, die PHP nicht leistet: Variablen lassen sich deklarieren. Das hat zwar keine Auswirkung auf den Code. Aber anhand der Dokumentation können Sie immer sehen, ob eine Variable in einer Klasse einen Integer, einen String oder andere Datentypen darstellt. Das geht mit folgenden Zeilen:

/**

* @var string enthält Überschrift

*/

var $headline

Den Namen der Variablen brauchen Sie im Kommentar selbst nicht angeben. Das Programm ordnet die Anmerkung automatisch der nachfolgenden Variablen zu.

Genauso geht es beim Kommentieren von Funktionen. Das kann zum Beispiel so aussehen:

/**

* Überschrift anzeigen

*

* Zeigt die Überschrift an, formatiert diese und speichert sie in der Datenbank.

* @param string $head enthält den Text der Überschrift

* @param int $groesse enthält die Schriftgröße

*/

function showHeadline($head, $groesse)

{ echo "<font size="$groesse">$head</font>";

}

Das Beispiel zeigt ein paar Spezialitäten: Die erste Zeile verwendet der Documentor als Kurzbeschreibung. Darauf lasse ich eine Leerzeile folgen und schreibe die ausführlichere Beschreibung zur Funktion. Mit @param teile ich dem Dokumentationssystem mit, welche Parameter die Funktion erwartet, welchen Typ sie haben und was sie bewirken. Im Gegensatz zu @var müssen Sie hier aber den Namen der Variablen dazu schreiben.

Im Kommentar für jede Klassendefinition sollte außerdem immer das Spezial-Tag @package stehen. Anhand dieses Tags sortiert später der Documentor die Klassen in Pakete. Das hilft, auch große Projekte und Klassenbibliotheken zu überblicken.

Verknüfpungen und Querverweise

Das ist längst nicht alles: phpDocumentor unterstützt Verknüpfungen und Querverweise, Sie können Autorennamen, Versionsnummern oder Beispiele eintippen. Und das Programm bindet Docbook-konforme Dateien als Tutorials ein. Neben der einfachen Funktionsreferenz können Sie hiermit ausführlich beschreiben, wie Ihre Klassen einzusetzen sind.

Also: Wenn Sie objektorientiert programmieren, holen Sie sich den phpDocumentor auf http://phpdoc.org. Eine Installationsanleitung und die ersten Schritte zur Bedienung finden Sie ebenfalls auf der Seite. Je früher Sie anfangen, Ihr Projekt zu dokumentieren, desto einfacher werden Sie sich und andere darin später zurechtfinden.

Ähnliche Beiträge