PHPDoc + Netbeans = schneller Entwickeln

Durch das Dokumentieren des Quellcodes kann man eine Menge Zeit sparen! PHPDoc und Netbeans bilden zusammen eine gute Kombination, um PHP-Code während der Entwicklung zu dokumentieren und auch die entstehende Doku zu benutzen. Viele denken vielleicht, dass die ausführliche Dokumentation für einen selbst nicht so wichtig ist, doch diesen Gedanken sollte man nochmal überdenken 😉

In PHP kann man in einer Variable alles speichern was man möchte, ohne auf den Datentyp zu achten. Das ist in dem Sinne gut, dass man sich zum Beispiel nicht groß mit Zahlenformaten und Konvertierungen beschäftigen muss. Es hat aber auch Nachteile: Woher soll man wissen, welcher Datentyp in einer Variable erwartet wird? Wenn man sich nicht ganz sicher ist, muss man auf die Suche gehen, was unnötig Zeit in Anspruch nimmt.

Mit PHPDoc kann man seinen Quellcode so dokumentieren, dass auch Datentypen angegeben werden können. Außerdem können weiterführende Links, Autoren und selbstverständlich Beschreibungen angegeben werden. PHPDoc selbst erzeugt eine Html-Dokumentation über alle Klassen, Funktionen und was es sonst noch so gibt.

Interessant wird PHPDoc, wenn die benutze IDE die Dokumentation auch nutzt. Dies macht unter anderem Netbeans, welches ich in diesem Artikel als Beispiel nutzen werde. Durch Netbeans werden bereits während der Eingabe von Klassen und Funktionen deren Definitionen angezeigt. So weiß man sofort, wie diese funktionieren. Wer keine Html-Doku möchte, kann die Funktion auch ohne eine extra Installation von PHPDoc nutzen.

Klassen

Eine Klasse kann man mit PHPDoc zum Beispiel so dokumentieren:

<?PHP
  /**
 * Exception, if access is denied
 * @package  ContentLion-Core
 * @author  Stefan Wienströer
 * @link  /exception-system-cms/
 */
  class AccessDeniedException extends ContentLionException{

Vor der eigentlichen Deklaration der Klasse ist hier ein Kommentar über mehrere Zeilen eingefügt. PHPDoc-Kommentare beginnen immer mit /**. Netbeans erleichtert die Eingabe und fügt bei einer neuen Zeile automatisch wieder einen Stern am Anfang ein und schließt den Kommentar auch.

Nun zur eigentlichen Deklaration. Ganz am Anfang kann eine globale Beschreibung der Klasse angegeben werden. Ist diese sehr umfangreich, kann man mit @link auch auf eine Detailseite verlinken.

Mit @package kann eine Klasse zu einem Paket zugeordnet werden. So muss man sich in der Html-Dokumentation später nicht durch tausende von Klassen suchen, sondern kann erst mal das Paket heraussuchen.

@author gibt den Autoren an und mit @link kann man zu einer erweiterten Beschreibung verlinken.

Wenn man jetzt in Netbeans den Namen der Klasse eintippt, bekommt man die Beschreibung bereits angezeigt:

Dokumentation von Klassen in Netbeans

Funktionen

Am wichtigsten ist meiner Meinung nach die Dokumentation von Funktionen. Hier mal ein Beispiel:

    /**
 * 
 * returns a datatype by name. Is null if nothing was found.
 * @param  string name of the datatype
 * @return  DataType founded datatype
 */
    public static function GetByName($name){

Durch @param können Parameter erstellt werden. Der Typ der Variable steht direkt danach und erst dann kommt die Beschreibung. Wenn man durch Voranstellung des Klassennamens in den PHP-Funktionen einen Typ erzwingt erkennt Netbeans automatisch und belegt schon den Typ des Parameters vor. Mit @return kann man die Parameter für einen Rückgabewert angeben.

In Netbeans sieht meine Funktion so aus:

Funktionen

In vielen Fällen kommt Netbeans auch mit Parametern zurecht 😉

Funktion mit Parametern

Variablen

Auch die Dokumentation einzelner Variablen ist möglich. Ob man jede einzelne dokumentiert bleibt natürlich jedem selbst überlassen:

    /**
 * Contains all instances of the setting class
 * @var  array 
 */
    protected static $instances  = array();

Mit @var kann hier der Datentyp angegeben werden. Ergebnis in Netbeans:

PHPDoc Variable in Netbeans

Fazit

PHPDoc und Netbeans sind ein gutes Team. Grade für Code, der auch von anderen benutzt wird, sollte man die Möglichkeit einer solchen Dokumentation in Betracht ziehen.

Du arbeitest in einer Agentur oder als Freelancer?
Dann wirf doch mal einen Blick auf unsere Software FeatValue.

Kommentare

Patrick schrieb am 30.10.2011:

Aus eigenen Erfahrungen kann ich nur sagen, dass die Dokumentation von Code EXTREM wichtig ist. Daneben sollte man natürlich auch noch Variablen und Funktionen entsprechend ihrer Semantik benennen. Wenn man an einem großen Projekt arbeitet ist die Dokumentation sowieso klar. Aber auch wenn man alleine was entwickelt und einem nach 5 Monaten einfällt, dass man doch noch was ergänzen möchte, ist man über jede Anmerkung im Code froh. Faulheit lohnt sich bei der Softwareentwicklung nicht wirklich und man vernichtet am Ende immer mindestens 3mal mehr Zeit, als wenn man es gleich richtig gemacht hätte.

Fahrplan für die Programmierung eines Webprojektes schrieb am 19.11.2011:

[...] bereits erstellen, aber die Funktionen noch leer lassen. Eine gute Idee wäre es, hier bereits PHPDoc [...]

Über uns

Wir entwickeln Webanwendungen mit viel Leidenschaft. Unser Wissen geben wir dabei gerne weiter. Mehr über a coding project