PHP-Kommentare verstehen

Kommentare sind Notizen, die Sie in Ihren Quellcode schreiben und die PHP beim Ausführen des Programms ignoriert. Sie existieren ausschließlich für Menschen — um zu erklären, warum ein Codeabschnitt das tut, was er tut, um Erinnerungen zu hinterlassen oder um Code während des Debuggens vorübergehend zu deaktivieren. Dieser Leitfaden behandelt jede Kommentarsyntax, die PHP unterstützt, wann man welche verwendet und welche Praktiken Kommentare hilfreich statt störend halten.

Dieses Kapitel setzt voraus, dass Sie bereits wissen, wie man grundlegendes PHP schreibt. Falls nicht, beginnen Sie zuerst mit den Kapiteln PHP-Syntax und PHP-Variablen.

Was sind PHP-Kommentare?

Ein Kommentar ist Text in Ihrem Code, den die PHP-Engine nicht ausführt. Wenn PHP eine Datei parst, überspringt sie Kommentare vollständig — sie beeinflussen niemals Ausgabe, Leistung oder Verhalten. Sie dienen als Dokumentation für jeden, der den Code als nächstes liest, einschließlich Ihres zukünftigen Ichs.

PHP unterstützt drei Kommentarstile, die in zwei Gruppen fallen:

• Einzeilige Kommentare, geschrieben mit // oder #.
• Mehrzeilige (Block-)Kommentare, geschrieben mit /* ... */.

PHP übernimmt die Stile // und /* */ von C und Java sowie den #-Stil von Shell-Skripten und Perl — egal aus welcher Sprache Sie kommen, einer davon wird sich vertraut anfühlen.

Einzeilige Kommentare

Ein einzeiliger Kommentar veranlasst PHP, den Rest der aktuellen Zeile zu ignorieren. PHP bietet Ihnen zwei austauschbare Marker dafür: // (C-Stil) und # (Shell-Stil). Sie verhalten sich identisch — wählen Sie einen und bleiben Sie innerhalb eines Projekts konsistent.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

Der Kommentar endet beim Zeilenumbruch, sodass die echo-Anweisungen weiterhin ausgeführt werden. Das obige Skript gibt Hello, world! Goodbye! Done. aus.

Mehrzeilige Kommentare

Ein mehrzeiliger Kommentar beginnt mit /* und endet mit */. Alles zwischen diesen Markierungen wird ignoriert, auch über viele Zeilen hinweg. Verwenden Sie ihn für längere Erklärungen oder um einen Codeblock auf einmal auszukommentieren.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

Die beiden echo-Anweisungen geben Visible output — still works aus; alles innerhalb von /* ... */ wird übersprungen.

Achtung — Blockkommentare lassen sich nicht verschachteln. PHP beendet den Kommentar beim ersten gefundenen */. Wenn Sie Code einschließen, der bereits einen /* ... */-Kommentar enthält, endet der äußere Block vorzeitig und das verbleibende */ verursacht einen Parse-Fehler. Um einen Codeabschnitt zu deaktivieren, der bereits Blockkommentare enthält, verwenden Sie stattdessen // oder # vor jeder Zeile.

Warum PHP-Kommentare verwenden?

PHP-Kommentare sind ein wichtiges Werkzeug für Entwickler, da sie dazu beitragen, Code leichter verständlich und wartbar zu machen. Durch das Hinzufügen von Kommentaren zu Ihrem Code können Sie den Zweck bestimmter Codezeilen erklären oder zusätzliche Informationen über den Code bereitstellen. Das erleichtert anderen Entwicklern das Verständnis und die Wartung Ihres Codes und hilft Ihnen auch, sich zu erinnern, was Ihr Code tut, wenn Sie später darauf zurückkommen.

Wie man PHP-Kommentare verwendet

Um Ihrem PHP-Code einen Kommentar hinzuzufügen, beginnen Sie die Zeile einfach mit zwei Schrägstrichen (für einzeilige Kommentare) oder einem Schrägstrich und einem Sternchen (für mehrzeilige Kommentare). Es ist wichtig, den geeigneten Kommentartyp basierend auf der Größe und Komplexität des zu kommentierenden Codes zu wählen.

Es ist auch wichtig sicherzustellen, dass Ihre Kommentare klar und prägnant sind und aussagekräftige Informationen über den Code liefern. Vermeiden Sie es, in Kommentaren einfach den Code zu wiederholen oder Offensichtliches zu beschreiben. Konzentrieren Sie sich stattdessen darauf, Informationen bereitzustellen, die aus dem Code nicht unmittelbar ersichtlich sind.

Code beim Debuggen auskommentieren

Eine der praktischsten Verwendungen von Kommentaren ist das vorübergehende Deaktivieren von Code ohne ihn zu löschen. Stellen Sie einer Zeile // oder # voran oder umschließen Sie mehrere Zeilen mit /* ... */, um sie aus dem Programm zu entfernen:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Denken Sie an die oben genannte Regel zur Nicht-Verschachtelung: Wenn der Code, den Sie deaktivieren möchten, bereits einen /* */-Block enthält, kommentieren Sie ihn zeilenweise mit // aus.

Dokumentationskommentare (PHPDoc)

Neben einfachen Kommentaren gibt es im PHP-Ökosystem eine Dokumentationskonvention namens PHPDoc. Es handelt sich um einen Blockkommentar, der mit /** (zwei Sternchen) beginnt und @-Tags verwendet, um Funktionen, Parameter und Rückgabewerte zu beschreiben. IDEs und Tools wie phpDocumentor lesen diese, um Autovervollständigung bereitzustellen und API-Dokumentation zu generieren.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc ist für die PHP-Engine technisch gesehen nur ein normaler /* */-Kommentar — er hat keine Laufzeitwirkung — aber die Einhaltung dieser Konvention macht Ihre Funktionen für Editoren und Teammitglieder viel leichter verständlich. Sie werden es ausgiebig im Kapitel PHP-Funktionen sehen.

Best Practices für PHP-Kommentare

Hier sind einige Best Practices, die beim Verwenden von PHP-Kommentaren zu beachten sind:

• Verwenden Sie klare und prägnante Sprache in Ihren Kommentaren
• Wiederholen Sie nicht den Code in Ihren Kommentaren — erklären Sie das Warum, nicht das Was
• Konzentrieren Sie sich darauf, Informationen bereitzustellen, die aus dem Code nicht unmittelbar ersichtlich sind
• Verwenden Sie angemessene Detailstufen in Ihren Kommentaren
• Halten Sie Ihre Kommentare aktuell, wenn sich Ihr Code weiterentwickelt — ein veralteter Kommentar ist schlimmer als keiner
• Bevorzugen Sie selbsterklärende Variablen- und Funktionsnamen gegenüber Kommentaren, die unklare erklären

Fazit

PHP-Kommentare sind ein unverzichtbares Werkzeug für Entwickler, das ihnen ermöglicht, ihren Code leichter verständlich und wartbar zu machen. PHP bietet Ihnen drei Syntaxen — // und # für einzelne Zeilen und /* ... */ für Blöcke — plus die PHPDoc-Konvention zur Dokumentation von Funktionen. Wenn Sie die in diesem Artikel beschriebenen Best Practices befolgen, können Sie PHP-Kommentare optimal nutzen und sicherstellen, dass Ihr Code gut dokumentiert und für andere Entwickler leicht verständlich ist.

Um weiterzulernen, fahren Sie mit PHP-Variablen und PHP-Operatoren fort.

Übungen