PHP Kommentare

Kommentare sind ein essenzielles Werkzeug in der PHP-Programmierung, um den Code verständlich und wartbar zu gestalten. Kommentare werden vom PHP-Interpreter ignoriert und haben somit keinen Einfluss auf die Ausführung des Programms. Sie dienen dazu, Code für Entwickler besser lesbar zu machen und sind besonders nützlich, um komplexe Logik, besondere Entscheidungen oder zukünftige Anpassungen zu dokumentieren.

In PHP gibt es verschiedene Arten von Kommentaren, darunter einzeilige und mehrzeilige Kommentare. Im Folgenden wird erläutert, wann und wie diese effektiv genutzt werden sollten.

Einzeilige Kommentare

Einzeilige Kommentare werden verwendet, um kurze Anmerkungen zu machen oder um eine spezifische Codezeile zu erklären. PHP bietet zwei Möglichkeiten, um einen einzeiligen Kommentar zu schreiben:

1. Doppel-Schrägstrich (//)
2. Raute (#)

Beispiel für einzeilige Kommentare

<?php
// Dies ist ein einzeiliger Kommentar mit Doppel-Schrägstrich
# Dies ist ein einzeiliger Kommentar mit Raute

$alter = 25; // Variable $alter speichert das Alter des Benutzers
?>

Die Variante mit // ist in der Praxis gebräuchlicher und wird häufig verwendet, da sie auch in anderen Programmiersprachen wie JavaScript vorkommt. Die #-Schreibweise stammt ursprünglich aus der Unix-Shell und wird seltener verwendet.

Best Practice: Verwende einzeilige Kommentare für kurze Erklärungen zu Variablen, Funktionsaufrufen oder spezifischen Anweisungen im Code. So bleibt der Code übersichtlich und leicht nachvollziehbar.

Mehrzeilige Kommentare

Mehrzeilige Kommentare sind hilfreich, wenn längere Erläuterungen oder Beschreibungen erforderlich sind. Sie beginnen mit /* und enden mit */. Zwischen diesen Zeichen kann beliebig viel Text stehen, auch über mehrere Zeilen.

Beispiel für mehrzeilige Kommentare

<?php
/* 
   Diese Funktion berechnet den Preis eines Produkts
   nach Abzug des Rabatts. Sie nimmt zwei Parameter entgegen:
   - $preis: Der ursprüngliche Preis des Produkts
   - $rabatt: Der Rabattsatz als Prozentwert
*/
function berechnePreis($preis, $rabatt) {
    return $preis - ($preis * $rabatt / 100);
}
?>

Best Practice: Mehrzeilige Kommentare eignen sich ideal, um Funktionsbeschreibungen, komplexe Logik und Dokumentationen zu mehreren Variablen oder Parametern bereitzustellen. Besonders bei umfangreichen Funktionen ist es empfehlenswert, diese Art von Kommentaren zu verwenden.

Dokumentationskommentare (PHPDoc)

Für umfassendere Projekte und insbesondere für die Zusammenarbeit in Teams ist es sinnvoll, eine standardisierte Form von Kommentaren zu verwenden, die eine formalisierte Dokumentation darstellt. Der PHPDoc-Standard ermöglicht es, Kommentare zu schreiben, die von speziellen Tools analysiert werden können, um automatisch Dokumentationen zu generieren.

PHPDoc-Kommentare beginnen wie mehrzeilige Kommentare mit /** und schließen mit */. Innerhalb eines PHPDoc-Kommentars können verschiedene Tags verwendet werden, um bestimmte Informationen zu dokumentieren, wie beispielsweise Parameter und Rückgabewerte einer Funktion.

Beispiel für einen PHPDoc-Kommentar

<?php
/**
 * Berechnet den Preis eines Produkts nach Abzug des Rabatts.
 *
 * @param float $preis Der ursprüngliche Preis des Produkts
 * @param float $rabatt Der Rabattsatz in Prozent
 * @return float Der reduzierte Preis
 */
function berechnePreis($preis, $rabatt) {
    return $preis - ($preis * $rabatt / 100);
}
?>

In diesem Beispiel werden die Tags @param und @return verwendet, um die Parameter und den Rückgabewert der Funktion zu dokumentieren.

Best Practice: PHPDoc-Kommentare sind ideal, um Funktionen, Klassen und Methoden zu dokumentieren. Sie bieten Struktur und helfen dabei, den Code sowohl für menschliche Leser als auch für Dokumentationsgeneratoren verständlich zu machen.

Wann sollte man Kommentare verwenden?

Kommentare sollten immer dann eingesetzt werden, wenn sie den Code verständlicher machen oder wenn komplexe Logik und spezifische Entscheidungen erklärt werden müssen. Gute Kommentare sind prägnant, informativ und auf den Punkt gebracht. Im Gegensatz dazu sind überflüssige Kommentare – etwa, wenn ein Kommentar exakt das beschreibt, was der Code bereits selbst erklärt – zu vermeiden.

Beispiele für hilfreiche Kommentare

Ungeeignete Kommentare:

<?php
$alter = 25; // Setzt die Variable $alter auf 25
?>

Geeignete Kommentare:

<?php
$alter = 25; // Das aktuelle Alter des Benutzers, um bestimmte Berechtigungen zu überprüfen
?>

Zusammenfassung und Best Practices für Kommentare in PHP

1. Konsistenz wahren: Ein- und mehrzeilige Kommentare einheitlich verwenden.
2. Dokumentation für Funktionen: Bei komplexen Funktionen oder Klassen sind PHPDoc-Kommentare die beste Wahl.
3. Kurze, aussagekräftige Kommentare: Vermeide überflüssige Kommentare, die den Code unnötig aufblähen.
4. Erklärung von Entscheidungsprozessen: Falls eine spezifische Implementierung gewählt wird, sollte die Entscheidung durch Kommentare begründet werden.

Häufig gestellte Fragen