PHP-Quellcode dokumentieren
Überblick behalten
Zeitersparnis
PHP-Quellcode dokumentieren
Jeder liebt eine gute Dokumentation ? wenn sie schon fertig geschrieben ist. Doch beim Programmieren selbst drücken sich viele vor dieser Arbeit oder vernachlässigen sie. Der Ärger kommt erst später, wenn man sich fragt, was diese eine Funktion eigentlich bewirkt und welchen Inhalt jene Variable haben sollte. Für die umständliche erneute Einarbeitung in den Code vergehen wertvolle Stunden, und die Arbeit dauert länger als notwendig.
Deshalb ist Dokumentieren des Programmierers erste Pflicht. Wichtig ist, gleich beim Schreiben des Codes damit anzufangen. Denn wer die Informationen erst hinterher anfertigt, häuft eine Menge Arbeit auf. Und je mehr Dokumentations-Arbeit wartet, desto weniger Lust hat man, sie zu erledigen.
Im Folgenden lesen Sie, wie Sie effektiv und Zeit sparend dokumentieren ? und wie Sie sich einige Dokumentationsarbeit sparen können. In erster Linie geht es in diesem Beitrag übrigens um die interne Dokumentation ? die Handbücher, die auch an die Anwender und Kunden gehen, sind noch ein ganz anderes Thema.
Code dokumentiert sich selbst
PHP-Quellcode dokumentieren
Dokumentation besteht nicht allein aus dem Einfügen von Kommentaren. Schon durch eine vernünftige Benennung von Klassen, Funktionen und Variablen erreichen Sie eine deutlich höhere Lesbarkeit und Verständlichkeit Ihres Codes. Hierzu ein Beispiel:
$a = "Hallo Erde";
// Viele 1000 Codezeilen
echo $a;
?>
Das Programm funktioniert einwandfrei. Was aber, wenn Sie 1000 Zeilen Code zwischen der Zuweisung des Wertes und der Ausgabe der Variable haben? Dann wissen Sie nicht mehr, welche Ausgabe Sie von $a zu erwarten haben.
Noch schlimmer wird es, wenn Variablenzuweisung und Ausgabe über mehrere Include-Dateien verteilt sind und Sie an einer komplexen Website mit vielen Ausgabezeilen arbeiten. Besser ist es, die Variablennamen so zu wählen, dass sie etwas über sich selbst aussagen, wie zum Beispiel:
$strGreeting = "Hallo Erde";
// Viele 1000 Codezeilen
echo $strGreeting;
?>
Hier wissen Sie auch noch 1000 Zeilen später, dass es sich um eine Variable handelt, die eine Zeichenkette (string) beinhaltet und zur Begrüßung dient. Natürlich können Sie auch deutschsprachige Bezeichnungen wählen, also etwa $strBegruessung;
Vorsicht nur mit Umlauten in Variablennamen. Die funktionieren zwar. Doch kann es zu Problemen kommen, falls der Quellcode einmal von einer anderen Plattform aus bearbeitet wird. Da kann es unter Umständen vorkommen, dass statt der Umlaute nur kryptische Sonderzeichen erscheinen.
Variablennamen
PHP-Quellcode dokumentieren
Die Methode, vor den eigentlichen Variablennamen einen Hinweis auf den Datentyp zu stellen, ist an die so genannte ungarische Notation angelehnt. Diese von einem gebürtigen Ungarn namens Simonyi stammende Schreibweise für Variablen versucht, möglichst viele Informationen in den Variablennamen zu packen.
Die Vorschläge der ungarischen Notation sehen je nach Quelle im Internet und nach Programmiersprache unterschiedlich aus. Für einen Integer-Wert kann i oder int vor den Namen gesetzt werden. Strings werden häufig mit psz, sz oder str deklariert. Allen Varianten ist ein Grundprinzip gemeinsam: Vor dem Variablennamen kommt die Information über den Variablentyp.
Für PHP könnten Sie zum Beispiel die folgenden Schreibweisen verwenden, welche sich allgemein als nützlich erwiesen haben:
- $intXXX ? Ganzzahlen
- $floatXXX oder $doubleXXX ? Gleitkommazahlen
- $arrXXX ? Array
- $boolXXX ? Boole-sches true oder false
- $objXXX ? Objekt
Oder Sie arbeiten mit kurzen Präfixes:
- $iXXX ? Ganzzahlen
- $fXXX oder $doubleXXX ? Gleitkommazahlen
- $aXXX ? Array
- $bXXX ? Boole-sches true oder false
- $oXXX ? Objekt
Wichtig ist, dass Sie eine Konvention durchhalten. Jede Minute, die Sie sich über die Einheitlichkeit der Schreibweisen Gedanken machen, sparen Sie später doppelt und dreifach wieder ein.
Lehrbücher für Java oder C# raten übrigens vom Einsatz der ungarischen Notation ab. In einer nicht streng typisierten Sprache wie PHP hingegen ist sie sehr hilfreich. Denn nur damit wissen Sie auch später noch, für welchen Datentyp die Variable ursprünglich eigentlich vorgesehen war.
Schreibweise
PHP-Quellcode dokumentieren
Meist bestehen Namen von Variablen oder Funktionen aus mehreren Wörtern. Schreiben Sie diese Wörter zusammen und beginnen Sie jedes neue Wort groß, zum Beispiel:
function getObjectData()
Ob Sie den ersten Buchstaben groß oder klein schreiben, bleibt Ihnen überlassen. Bei Variablennamen sieht unserer Meinung nach die Kleinschreibung besser aus, also
$intLevel = 0;
statt:
$IntLevel = 0;
Übrigens achtet PHP selbst nicht auf die Groß- und Kleinschreibung. Der folgende Ausschnitt funktioniert bei PHP trotz der unterschiedlicher Schreibweisen einwandfrei:
displaySomeData();
DISPLAYSOMEDATA();
function displaySomeData()
{
echo "\nSome Data";
}
?>
Hier erscheint zwei Mal Some Data als Ausgabe. Achten Sie dennoch immer auf die richtige Schreibweise ? falls Sie einmal in einer anderen Sprache programmieren, fällt Ihnen so die Umstellung leichter.
Gute Namen finden
PHP-Quellcode dokumentieren
Nun gilt es nur noch, geeignete Namen für die Variablen und Funktionen zu finden. Zunächst die Entscheidung für die Sprache: Deutsch oder Englisch? Wie Sie sich auch entscheiden ? halten Sie die Sprache auf jeden Fall durch.
Klassen und daraus entstehende Objekte sollten Sie grundsätzlich mit Substantiven benennen, also
class classText
oder:
$objText = new classText();
Methoden oder Funktionen lassen sich meist mit einem Verb gut beschreiben, wie zum Beispiel:
function readText()
Aber Achtung: In dieses Beispiel ist schon eine kleine Falle eingebaut: Was bedeutet eigentlich read? Heißt das nun, die Funktion liest einen Text ein, oder bedeutet es, dass der Betrachter der Seite einen Text ansehen darf? Im Normalfall tippt man auf die erste Variante, also die Funktion liest etwas ein.
Aber der Eindeutigkeit halber könnte man die Funktion deshalb folgendermaßen bennen:
function readTextFromDb()
Wenn Sie eine Methode benennen, können Sie in diesem Beispiel auf das Text verzichten. Denn das Objekt deutet ja schon an, dass es um Text geht, also nehmen Sie:
$objText->readFromDb();
Namen von Variablen und Eigenschaften sind meist auch Substantive, also:
$strName = 'Muster';
Die Kommentare
PHP-Quellcode dokumentieren
In PHP gibt es zwei Arten von Kommentaren: Einzeilige Kommentare beginnen mit einem doppelten Schrägstrich, zum Beispiel:
// ID-Nummer des Beitrags
Die andere Variante sind mehrzeilige Kommentare. Sie beginnen mit /* und enden mit */, also:
/*
Das ist ein Kommentar, der sich
über mehrere Zeilen erstreckt.
*/
Der einzeilige Kommentar passt auch hervorragend hinter den Quellcode, zum Beispiel:
$intCounter = 0; // Datensatzzähler
Was und wie kommentieren?
PHP-Quellcode dokumentieren
Wenn Sie die Regeln zur Benennung von Variablen und Funktionen beachten, ist ein wesentlicher Teil der Dokumentationsarbeit bereits erledigt. Denn gut lesbarer Code erklärt sich fast von selbst. In den Kommentaren müssen Sie also nicht mehr unbedingt notieren, wie etwas funktioniert. Sie können sich im Quelltext weitgehend auf Kommentare beschränken, die sagen, warum Sie etwas gemacht haben.
Außerdem ist es sinnvoll, jeder Funktion oder Methode einen Kommentar mitzugeben. Der beschreibt die Funktion und zeigt, welche Parameter sie verlangt. Zusätzlich ist eine Auskunft über den Rückgabewert sinnvoll. Das gilt auch für Klassen und deren Methoden. Innerhalb von Funktionen sollten Sie Kommentare möglichst sparsam verwenden. Sonst wird der Code zu unübersichtlich. Hier eignen sich die Einzeiler hinter dem Code am besten. So bleiben der Quelltext und dessen Struktur lesbar.
Schließlich sollte auch jede PHP-Datei am Anfang einen Kommentar enthalten. Dieser erklärt, was die Datei macht, zu welchem Projekt sie gehört und wer sie wann programmiert hat.
Bei den Kommentaren an sich gilt: knapp und verständlich halten. Schreiben Sie keine Romane, weshalb und wie genau Sie die Funktion programmiert haben. Bedenken Sie immer, dass möglicherweise auch andere die Dokumentation einmal lesen und schnell verstehen wollen. Falls Sie überlegen, Ihr Skript im Internet zum Download freizugeben, schreiben Sie die Kommentare am besten gleich auf Englisch.
Vermeiden sollten Sie jede Art von Flapsigkeit ? auch wenn es witzig sein sollte. Denn möglicherweise liest irgendwann ein anderer den Quellcode. Da wirkt dann der vermeintliche Scherz meist nur noch peinlich.
Nach Möglichkeit sollten Sie sich auch mit Selbstkritik und To-do-Listen innerhalb des Quelltextes zurückhalten. Kommentare sind während der Entwicklungsphase noch in Ordnung, sie sollten aber gestrichen werden, sobald Sie fertig sind. Denn solche Kommentare bringen andere Leser auf den Gedanken, dass Ihre Software nicht ausgereift ist und dass Sie selbst nicht zu Ihrem Werk stehen ? und Ihre Software ist doch ausgereift, oder etwa nicht?
phpDocumentor
PHP-Quellcode dokumentieren
Jetzt kommt der angenehme Teil: Mit ein wenig Aufwand kann man automatisch eine Dokumentation seines kompletten Quelltextes anfertigen lassen. Das lohnt sich umso mehr, je größer ein Projekt ist. Denn hat man erst einmal zehn oder zwanzig Dateien mit Klassen und Funktionen, wird es schnell unübersichtlich. Möglicherweise wissen Sie nicht einmal mehr, in welcher Datei eine Methode oder Variable überhaupt steckt. Hier ist eine gute Dokumentation das A und O.
Der phpDocumentor hilft Ihnen dabei. Das als Open Source veröffentlichte Programmpaket durchsucht PHP-Dateien nach Klassen, Funktionen und Kommentaren. So entsteht im Handumdrehen eine Übersicht über das komplette Programmierprojekt.
Noch besser wird das Ergebnis, wenn Sie ein paar Standards beim Kommentieren einhalten. Das ? bei Javadoc entlehnte ? Prinzip ist einfach. Kommentare werden immer mit /** eingeleitet. Vor jeder Kommentarzeile steht ein *, den Abschluss bildet */. Ein Beispiel:
/**
* Ein Kommentartext
*/
Ein solcher Kommentar wird der nächstfolgenden Funktion oder Variablen zugerechnet und taucht in der Dokumentation als Beschreibung auf.
Sollen es ein wenig mehr Informationen sein? Dann brauchen Sie die speziellen Tags von phpDocumentor. Ein Beispiel hierzu:
/**
* Überschrift anzeigen
* @author Max Muster
* @param string $strHead
* @param int $intGroesse Groesse der Schriftart
* @return string
*/
function showHeadline($strHead, $intGroesse)
{
return "$strHead";
}
Die erste Zeile verwendet der Documentor wie gehabt als Kurzbeschreibung. Darauf folgt der Name des Autors samt seiner E-Mail-Adresse in spitzen Klammern. Weiter geht es mit den Parametern. Mit @param deuten Sie an, welchen Datentyp die Parameter beinhalten und wie sie heißen. Zusätzlich können Sie wie in der zweiten @param-Zeile noch eine kurze Beschreibung des Parameters eingeben. @return gibt Aufschluss darüber, welchen Datentyp die Funktion zurückgibt.
Bei Variablen innerhalb von Klassen informiert phpDocumentor auf Wunsch über den Typ von Variablen ? zumindest über den Typ, den sich der Programmierer wünscht.
Dazu allerdings ist ein spezielles Tag notwendig. Und das sieht folgendermaßen aus:
/**
* @var string Überschrift
*/
var $strHeadline
Den Namen der Variablen geben Sie im Kommentar nicht mit an. Allerdings wird es unübersichtlich, wenn man 20 Variablen deklariert ? und dazu 80 Zeilen Quelltext braucht. Auf dieses Feature kann man zu Gunsten einer eindeutigen Schreibweise der Variablen auch notfalls verzichten.
Zusätzlich unterstützt phpDocumentor Verknüpfungen und Querverweise zu anderen Seiten in der Dokumentation. Sie dürfen auch Versionsnummern oder Programmbeispiele mit in die Dokumentation aufnehmen. Weiterhin bindet das Programm Docbook-konforme Dateien als Tutorials ein. So können Sie umfangreiche Tutorials erzeugen und als HTML-Seiten speichern.
Den phpDocumentor finden Sie auf www.phpdoc.org.
Dokumentieren mit der ZDE
PHP-Quellcode dokumentieren
Auch die Entwicklungsumgebung Zend IDE (ZDE) unterstützt Javadoc-ähnliche Kommentare. Die ZDE listet im Fenster Inspect alle Funktionen und Methoden einer Datei oder eines Projekts auf. Nach einem Klick mit der rechten Maustaste auf den Funktionsnamen kann man mit Add Description eine Beschreibung hinzufügen. Hierbei fügt die ZDE das Tag @desc in einen Kommentar vor der Funktion ein, um die Beschreibung zu markieren. Diesen Bezeichner kann der Programmierer aber auch weglassen, um konform mit phpDocumentor zu bleiben. Die Beschreibung erscheint trotzdem hinterher als Tooltipp in der automatischen Ergänzung sowie in der Funktionsliste. Auch @param und @return fügt die ZDE ein, falls die Funktion Parameter und Rückgabewert hat.
Änderungen im Changelog
PHP-Quellcode dokumentieren
Bei größeren Projekten sollten Sie ein Logbuch schreiben. Solchen Dokumenten begegnen Sie in der Software-Szene allenthalben unter dem Dateinamen changelog. Wie Sie so ein Log führen, ob mit Versionsnummern oder ohne, bleibt Ihnen überlassen. Wichtig ist aber, dass Sie darin alle Änderungen notieren und jeweils ein Datum dazuschreiben.
Ein solches Log hat viele Vorteile: Es dient als Arbeitsnachweis und als Spickzettel, falls der Kunde fragt »Was gibt es Neues im Programm?«.