mijane Blog

ein paar interessante Sachen gibt es immer

Warum PHP Doc Blocks?

Geschrieben von Peter Rother • Sonntag, 11. Januar 2009 • Kategorie: Doc Blocks


Je umfangreicher ein Projekt wird, desto wichtiger wird die Dokumentation. Kommentare helfen, den Programmcode besser zu verstehen. Nach einiger Zeit wissen selbst die Progammierer nicht mehr, was sie vor x Wochen oder Monaten geschrieben haben. Hier kommen die Doc Blocks ins Spiel. Jede Klasse und / oder Methode sollte mit einem Kommentar versehen werden.
Der eigentliche Quellcode sollte durch Aussagekräftige Variablen und Methoden selbst erklärend sein. Ich finde das, wenn man einen Kommentar in einer Methode oder Funktion benötigt, der Code zu umständlich geschrieben ist.

Was genau sollte ein Doc Block erklären? Hier folgt ein kleiner Überblick:

  • welche Aufgabe hat die Funktion / Methode
  • welche Parameter erwartet sie
  • welchen Datentyp gibt sie zurück

Wie genau ist ein Doc Block aufgebaut?

/**
* Hier steht was genau in der Methode passiert
*
* @param int $sId
* @return string
*/

@param gibt an welche Parameter von der Methode benötigt werden.
@return gibt an welcher Typ von der Methode zurück gegeben wird


Der Doc Block wird direkt vor der Klasse oder der Methode angegeben und beginnt mit den Zeichen /**. Jede neue Zeile beginnt mit einem * und das Ende des Doc Blocks wird mit */ eingeleitet.

Eine Auflistung aller Doc Block Tags werde ich demnächst hier vorstellen.
Tags für diesen Artikel: ,
Artikel mit ähnlichen Themen:
Friend of a Friend
Magische Methoden
20 Tips für schnelleren PHP Code
phpDocumentor installieren
Start einer Serie zum Thema Doc Blocks
Tweet This!Tweet This!

1 Trackbacks

Trackback für spezifische URI dieses Eintrags
  1. mijane Blog » Start einer Serie zum Thema Doc Blocks am Jan 24, 20:41: Eine Serie zu einem bestimmtem Thema ist doch immer was nettes, so sehe ich das wenigstens. Also habe ich mir vorgenommen hier eine Serie zum Thema Doc Blocks in PHP zu starten. Als Doc Block Engine habe ich mir phpDocumentor ausgesucht, da ich hiermit

2 Kommentare

Ansicht der Kommentare: (Linear | Verschachtelt)
  1. unset am 12.01.2009 09:31: Bei Team-Projekten sind die Tags "author" und "since" auch nicht verkehrt. Aber auf aufgepasst: Einen offiziellen Standard gibt is meines Wissens leider nicht. Eclipse beherrscht allerdings sowas wie einen Pseudostandard so gut wie komplett.
  2. Peter Rother am 13.01.2009 12:23: Da stimme ich dir zu. Bei Team Projekten sollten man die Tags auf jeden Fall einsetzen. Ich richt mich bei der Auswahl der Tags an denen die von http://www.phpdoc.org/ vorgegeben sind. Ob diese schon Standard sind wüsste ich momentan auch nicht. Wenn man sich ein bißchen mit den Doc Blocks beschäftigt hat, sollte eigentlich fast jeder wissen was gemeint ist (und mit der standardisierung ist das ja leider immer so eine sache).
    Ich werde im laufe dieser Woche einmal die Liste komplett überarbeiten und auch die PHPUnit Tags mit erklären.

Kommentar schreiben


Umschließende Sterne heben ein Wort hervor (*wort*), per _wort_ kann ein Wort unterstrichen werden.
Standard-Text Smilies wie :-) und ;-) werden zu Bildern konvertiert.

Um maschinelle und automatische Übertragung von Spamkommentaren zu verhindern, bitte die Zeichenfolge im dargestellten Bild in der Eingabemaske eintragen. Nur wenn die Zeichenfolge richtig eingegeben wurde, kann der Kommentar angenommen werden. Bitte beachten Sie, dass Ihr Browser Cookies unterstützen muss um dieses Verfahren anzuwenden.
CAPTCHA


Kommentare werden erst nach redaktioneller Prüfung freigeschaltet!