PHP Multiline Comments

Mehrzeilige Kommentare in PHP sind ideal, um ausführliche Erklärungen, Funktionsbeschreibungen oder Dokumentationen für größere Codeabschnitte bereitzustellen. Diese Kommentare beginnen mit /* und enden mit */, wodurch beliebig viele Zeilen zwischen den Markierungen verwendet werden können.

Der Einsatz von mehrzeiligen Kommentaren bietet sich vor allem dann an, wenn komplexe Logik oder längere Anmerkungen im Code notwendig sind. In PHP können zwei verschiedene Arten von mehrzeiligen Kommentaren genutzt werden: reguläre Blockkommentare und PHPDoc-Kommentare.

Mehrzeilige Blockkommentare

Blockkommentare können überall im Code eingesetzt werden, um detaillierte Erklärungen zu geben. Sie eignen sich besonders gut für:

• Dokumentation komplexer Logik
• Erklärungen für Code-Abschnitte oder Schleifen
• Hinweise zu spezifischen Entscheidungen im Code

<?php
/* 
   Diese Funktion berechnet den Endpreis eines Produkts,
   nachdem ein Rabatt angewendet wurde. Sie benötigt zwei Parameter:
   - $preis: Der Basispreis des Produkts
   - $rabatt: Der Rabatt in Prozent
*/
function berechneEndpreis($preis, $rabatt) {
    return $preis - ($preis * $rabatt / 100);
}
?>

Dieser Kommentarblock beschreibt, was die Funktion tut und welche Parameter benötigt werden. Dadurch wird die Funktion für andere Entwickler besser nachvollziehbar und wartbarer.

Dokumentationskommentare mit PHPDoc

PHPDoc ist ein Kommentarstandard in PHP, der eine formalisierte Dokumentation für Funktionen, Klassen und Methoden ermöglicht. Kommentare im PHPDoc-Stil beginnen mit /** und enden mit */. Sie enthalten spezielle Tags, die von automatischen Dokumentationswerkzeugen erkannt und verarbeitet werden, z. B. @param für Parameter und @return für Rückgabewerte.

Beispiel für einen PHPDoc-Kommentar

<?php
/**
 * Berechnet den Endpreis eines Produkts nach Abzug eines Rabatts.
 *
 * Diese Funktion nimmt zwei Parameter entgegen: den Basispreis und
 * den Rabattsatz. Sie gibt den berechneten Endpreis zurück.
 *
 * @param float $preis Der Basispreis des Produkts
 * @param float $rabatt Der Rabatt in Prozent
 * @return float Der Endpreis nach Abzug des Rabatts
 */
function berechneEndpreis($preis, $rabatt) {
    return $preis - ($preis * $rabatt / 100);
}
?>

In diesem Beispiel erklärt der Kommentar die Funktion und ihre Parameter, während die PHPDoc-Tags zusätzliche Informationen für Dokumentationsgeneratoren bereitstellen.

Vorteile von PHPDoc-Kommentaren

1. Automatische Dokumentation: PHPDoc-Kommentare können von Tools wie PHPDocumentor verarbeitet werden, um eine vollständige Dokumentation zu generieren.
2. Standardisierte Struktur: Durch die Verwendung von Tags wie @param und @return erhalten Entwickler eine konsistente und leicht verständliche Dokumentation.
3. Einfache Integration in IDEs: Viele integrierte Entwicklungsumgebungen (IDEs) wie PHPStorm erkennen PHPDoc-Kommentare und bieten zusätzliche Funktionen wie Tooltipps und Autovervollständigung.

Best Practices für mehrzeilige Kommentare

• Verwende PHPDoc-Kommentare für öffentliche Funktionen und Klassen: Dadurch wird eine formale Dokumentation erstellt, die in größeren Projekten unverzichtbar ist.
• Setze Blockkommentare gezielt ein: Nutze Blockkommentare, um größere Codeabschnitte oder komplexe Logik verständlicher zu machen.
• Kurze und prägnante Formulierungen: Halte die Kommentare prägnant und beschränke dich auf relevante Informationen.

Häufig gestellte Fragen