PHP 4.3

14.8.5 Beschreibende Kommentare

Eine Datei sollte, insbesondere wenn das darin enthaltene Skript komplexere Aufgaben löst, einen Dateikopf besitzen. Dieser Kopf ist ein zusammenhängender mehrzeiliger Kommentar, in dem Sie für sich selbst und für andere beschreiben, was die Datei ausmacht, also, was das Skript leistet, welches die wichtigsten Variablen sind und welche Daten das Skript benötigt. Zweckmäßig ist die Information über den Zeitpunkt der letzten Änderung der Datei und natürlich die Nennung Ihres Namens als Verfasser. Der Dateikopf kann z.B. so aufgebaut sein:

/**
* Programmiersprache und Version
*
* Anmerkungen zur Programmiersprache
*
* Programmname / Dateiname
*
* Versionsnummer
*
* Mehrzeilige detaillierte Beschreibung.
* Die mehrzeilige Beschreibung sollte den allgemeinen Zweck des Programms
* bzw. der Datei erläutern. Diese Beschreibung sollte Hinweise auf die
* verwendeten Bibliotheken und wichtige Variablen enthalten.
*
* Autor(en)
* Liste der Autoren (optional mit Angabe der E-Mailadresse)
*
* Änderungen
* Liste der Änderungen, jeweils unter Angabe des Datums, der Beschreibung
* der Änderung selbst und des Autors der Änderung
*
*/

Es ist auch sehr sinnvoll, Funktionen, die eine gewisse Größe überschreiten, mit einem etwas ausführlicheren Kopf zu versehen, in dem alle Informationen stehen, die man zur Benutzung der Funktion benötigt. Dazu zählen insbesondere Angaben zur Bedeutung der Parameter und des Rückgabewerts.

/**
* Kurze Beschreibung und Name der Funktion
*
* Mehrzeilige detaillierte Beschreibung.
* Die mehrzeilige Beschreibung sollte den allgemeinen Zweck der Funktion
* erläutern.
*
* Parameter
* Erläuterung zulässiger / notwendiger Parameter und ihrer Datentypen
*
* Rückgaben
* Erläuterung der möglichen Rückgabewerte der Funktion inkl. Datentyp
*
*/

Kommentare (0)

Ihr Kommentar

Name