Kommentare in PHP

Beschreibung der drei verschiedenen Möglichkeiten, Kommentare in PHP zu platzieren

Kommentare sind Textzeilen, die nur im Code erscheinen und später nicht ausgegeben werden.
Sie dienen dazu, die übersicht im Code zu verbessern und das Verständnis zu erleichtern.
Kommentare sind umso nützlicher, je umfangreicher und komplizierter der Code ist.
Auch eigenen Code sollte man immer kommentieren.
Andernfalls wird man selbst Probleme haben, diesen zu verstehen, wenn man ihn länger nicht mehr gesehen hat.

Kommentare werden immer mit bestimmten Zeichen eingeleitet und enden entweder am Zeilenende oder an bestimmten anderen Zeichen, die das Ende des Kommentars markieren.
Es gibt drei Wege, in PHP im Code Kommentare zu platzieren:

// ...: Dieses Kommentar wird mit zwei Schrägstrichen eingeleitet und endet am Ende der Zeile.
# ...: Dieses Kommentar wird von einem Doppelkreuz eingeleitet und endet am Ende der Zeile.
/* ... */: Dieses Kommentar wird mit /* eingeleitet und endet, sobald ein */ gefunden wird.

Das Kommentar mittels Doppelkreuz (# blabla) ist selten, die doppelten Schrägstriche sollten daher bevorzugt werden.
Beispielhafter Code zur Demonstration der Kommentare:

PHP-Code

<?php
    // Einzeilige Kommentare können mit doppelten Schrägstrichen eingeleitet werden
	// Noch etwas Kommentierung
	echo("Das vorherige Kommentar wurde nicht angezeigt.\n");
	
	# Das ist ein einzeiliges Kommentar, das mit einem Doppelkreuz eingeleitet wurde.
	echo("Das vorherige Kommentar wurde nicht angezeigt.\n");

	/*
		Mehrzeilige Kommentare werden mit einem
			Schrägstrich und einem darauf folgenden Multiplikationszeichen
	   	eingeleitet. Beendet werden sie mit
			einem Multiplikationszeichen und einem darauf folgenden Schrägstrich.
	*/
	echo("Das vorherige Kommentar wurde nicht angezeigt.");
?>

Ausgabe

Das vorherige Kommentar wurde nicht angezeigt.
Das vorherige Kommentar wurde nicht angezeigt.
Das vorherige Kommentar wurde nicht angezeigt.

Zur Kommentierung von Funktionen, Methoden und Klassen ist es Konvention, vor diesen ein mehrzeiliges Kommentar zu platzieren, welches am Anfang
ein zweites Multiplikationszeichen und einen Zeilenumbruch hat.

PHP-Code

<?php
	/**
	 * Dies ist ein Kommentar extra für die Funktion doSomething().
	 */
	function doSomething() {
		...
	}
?>

Zur weiteren Verbesserung der Übersicht werden in diesem speziellen Kommentar häufig Angaben gemacht bezüglich der erlaubten Parameter der Funktion/Methode und deren Rückgaben. Der Aufbau dieser Angaben ist wie folgt:

Parameter: @param Datentyp $name Beschreibung
Rückgabe: @return Datentyp Beschreibung

Beispiel:

PHP-Code

<?php
	/**
	 * Multipliziert zwei Zahlen miteinander und gibt das Ergebnis zurück.
	 * @param mixed $zahl1 Die erste Zahl
	 * @param mixed $zahl2 Die zweite Zahl
	 * @return float Das Ergebnis der Multiplikation
	 */
	function multipliziere($zahl1, $zahl2) {
		return (float)((float)$zahl1 * (float)$zahl2);
	}
?>

Die Formulierung „mixed” heißt hier, dass der Parameter entweder vom Datentyp Float oder vom Datentyp Integer sein darf.
Mehr Informationen zu diesen sogenannten Doc Comments finden sich hier.
Weitere Tags (@tag) finden sich unter http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html.