Jeder kennt das Problem bei größeren Projekten. Man macht sich meistens erst im Nachhinein die Gedanken eine saubere Dokumentation für das Projekt bzw. für seine Module zu erstellen. Das kostet meistens sehr viel Zeit und verlangt nach unzähligen sich wiederholenden Aufgaben, wie Sourcecode öffnen, Klasse bzw. Methode nachschlagen, sich eine kurzen Text überlegen. Bei Projekten, die man nur für sich bzw. alleine realisiert mag das auch ein praktikables Verfahren sein, sobald man jedoch in einem Team tätig wird, sollte man auf professionelle Tools zurückgreiffen und die Dokumentation schon bei Beginn des Projektes in den Workflow integrieren.

In PHP gibt es analog zu Java einige sehr interessante Tools, mit denen man diese Arbeit professionell strukturieren und ausführen kann. Die zwei Tools die ich in meinen Projekten verwende sind phpDocumentor [1] und PHPXref [2], beides Open Source Tools, welche auf phpDoc aufbauen, ein Standard der sich sehr stark an den Javadoc Standard orientiert.

Bei phpDoc jedoch sollte die Arbeit der Dokumentation schon während der Erstellung des Sourcecodes erfolgen. Dies macht man am besten, in dem man sich erst mal die verschiedenen Tags in der Dokumentation [3] ansieht, die man in den so genannten DocBlock eines Kommentars einfügt. Ein DocBlock für eine Klasse sieht dann in etwa so aus:


/**
* GUI class
*
* Class responsible for the GUI management. In the MVC paradigma
* responsible for the view components.
* Serves as gui management in combination with smarty template engine
*
* @version 3.0
* @copyright Copyright © 2003-2004, Dino Karl
* @author Dino Karl
*/


Diese DocBlocks setzt man vor seine Methoden/Funktionen, zu Beginn der prozeduralen Skripte und Klassen. Damit erhält man jederzeit mit Hilfe von phpDocumentor eine sehr strukturierte API Dokumentation, die man auch noch sehr schnell in diverse Formate bzw. Darstellungsformen bringen kann (HTML, PDF, MS Help Format, etc.).

Ein weiterer Vorteil dieser Art von Dokumentation ist, dass in einigen Entwicklungsumgebungen wie z.B. der Zend IDE gewisse Hilfemechanismen zur Verfügung stehen, bei denen bei der weiteren Programmierung Hilfetexte und Methoden/Funktionsparameter aufgelistet werden.

Da es bei PHP eigentlich keine Rolle spielt, wie man seinen Code schreibt bzw. wie man seinen Sourcecode strukturiert, sollte man sich an professionelle PHP Bibliotheken wie PEAR orientieren. Die PEAR Dokumentation beinhaltet ein sehr informatives Kapitel über Coding Standards [4], welche man zum Großteil für seine eigenen Projekte bzw. als Richtlinie für gemeinsame Projekte übernehmen sollte.

Um nun noch ein Überblick über das gesamte Projekt, vor allem über die gesamten Referenzen eines Projektes zu bekommen sollte man noch das Open Source Tool phpXref [1] einsetzen. Dieses Tool analysiert alle Dateien in einem Projekt und stellt eine Liste mit allen Referenzen innerhalb eines Projektes zusammen. Möchte ich z.B. wissen wo meine Funktion foo() überall aufgerufen wird, zeigt mir die phpXref Dokumentation genau an, in welchen anderen Dateien/Skripts diese Funktion aufgerufen wird. Eine Demonstration dieser Funktionen kann man in der Dokumentation des CMS Frameworks Xaraya [5] ausprobieren

Des weiteren sollte man auch nicht vergessen, das Datenbankschema zu dokumentieren. Dazu findet sich mit fabForces DBDesigner [6] ein sehr einfaches Tool, mit dem automatisch das Schema einer mySQL Datenbank analysiert und grafisch dargestellt wird. Ich habe über dieses Tool schon in einem kurzen Artikel [7] geschrieben.

Nun haben wir die gesamten Punkte in Bezug auf die API Dokumentation aufgezählt. Normalerweise reicht diese Dokumentation für die meisten Programmierer auch aus, um sich schnell ein ein Projekt einzuarbeiten. Sollte man jedoch noch weitere Dokumentation zu einem Projekt erstellen wollen, so sei noch auf den XML Standard DocBook hingewiesen. Dieses Format wird in phpDocumentor verwendet um nicht API Dokumentation zu erstellen. Da dieses Format nicht automatisch von den meisten Textverarbeitungsprogrammen unterstützt wird gibt es zusätzliche Tools, normale Dokumente ins DocBook Format umzuwandeln. Dazu habe ich ein sehr hilfreiches Wiki [8] gefunden, welches das Zusammenspiel zwischen OpenOffice und DocBook erklärt und auf die richtigen Plugins hinweist.

Mit all diesen Hilfsmitteln sollte es nun sehr einfach sein, eine aussagekräftige Dokumentation für jedes Projekt zu erstellen. Gerade bei größeren Projekten ist die Verwendung von solchen Hilfsmitteln nicht mehr wegzudenken. Aber auch bei kleineren Projekten sollte man sich die zusätzliche Mühe machen, damit man sich auch selber später wieder sehr schnell in Code einarbeiten kann, den man vor Jahren erstellt hat.

[1] http://phpdocu.sourceforge.net/
[2] http://phpxref.sourceforge.net/
[3] http://phpdoc.org/docs/
[4] http://pear.php.net/manual/de/standards.php
[5] http://phpxref.sourceforge.net/phpxref-xaraya/nav.html.gz?index.html.gz
[6] http://www.fabforce.net/dbdesigner4/
[7] http://wordpress.dinokarl.com/index.php?p=41
[8] http://www.docbook.org/wiki/moin.cgi/OpenOffice