Dokumentation in PHP: Wie man Code schreibt, den man nicht zu zeigen schämt

Ihr Code spricht lauter als Worte? Nein, wenn Sie in PHP schreiben

Stellen Sie sich vor: Sie öffnen ein altes PHP-Projekt, das Sie vor einem halben Jahr geschrieben haben. Sie betrachten die Funktion processData() und verstehen... rein gar nichts. Welche Daten? Woher kommen sie? Warum heißt die Methode doMagic()? Kommt Ihnen das bekannt vor? Wenn ja, ist dieser Artikel für Sie.

Gute Dokumentation in PHP ist nicht nur eine "Höflichkeit" gegenüber Kollegen. Sie ist Ihre Versicherung gegen Kopfschmerzen, beschleunigt das Onboarding neuer Entwickler und letztendlich die Qualität Ihres Produkts. In diesem Artikel werden wir die Best Practices für die Dokumentation von PHP-Code durchgehen, die Ihren chaotischen Code in ein klares, verständliches System verwandeln.

Warum ist Dokumentation in PHP keine "unnötige Arbeit"?

Viele Entwickler glauben, dass "guter Code für sich selbst spricht". Das stimmt nur teilweise. Guter Code erklärt wie er funktioniert, aber er erklärt selten warum und weshalb genau so. Die Dokumentation schließt diese Lücken. Sie beantwortet die Fragen:

\n
• Welche Eingabedaten erwartet die Funktion?
\n
• Was gibt sie im Fehlerfall zurück?
\n
• Warum wurde diese architektonische Entscheidung getroffen?
\n
• Welche Nebeneffekte hat die Methode?
\n

Ohne Antworten auf diese Fragen ist Ihr Code eine Blackbox. Und Blackboxen scheuen sich selbst erfahrene Entwickler anzufassen.

PHPDoc: Ihr wichtigstes Werkzeug

Der De-facto-Standard für die Dokumentation von PHP-Code ist PHPDoc. Dies ist ein spezielles Kommentarformat, das mit /** beginnt und mit */ endet. Es wird von allen modernen IDEs (PhpStorm, VS Code) und Dokumentationsgenerierungstools wie phpDocumentor oder Doxygen unterstützt.

Die grundlegende Syntax von PHPDoc umfasst:

\n
• @param — Beschreibung der Parameter einer Methode oder Funktion
\n
• @return — Typ und Beschreibung des Rückgabewerts
\n
• @throws — Welche Ausnahmen die Methode werfen kann
\n
• @var — Typ einer Klasseneigenschaft
\n
• @see — Verweis auf eine verwandte Methode oder Klasse
\n
• @deprecated — Kennzeichnung, dass die Funktionalität veraltet ist
\n

Beispiel eines guten PHPDoc-Blocks

<?php\n\n/**\n * Berechnet den Endpreis einer Bestellung inklusive Rabatt und Steuern.\n *\n * Diese Methode wendet eine progressive Rabattstaffel basierend auf dem Bestellwert an.\n * Wenn der Betrag 10.000 Rubel übersteigt, wird der maximale Rabatt von 15% gewährt.\n *\n * @param float $basePrice Grundpreis der Bestellung ohne Rabatte (in Rubel).\n * @param float $taxRate   Steuersatz, z.B. 0.20 für 20%.\n * @param string $currency Währung zur Formatierung des Ergebnisses (Standard 'RUB').\n *\n * @return string Formatierte Zeichenfolge mit dem Endpreis, z.B. "12 500.00 ₽".\n *\n * @throws \\InvalidArgumentException Wenn der Grundpreis negativ ist.\n * @throws \\RuntimeException         Wenn der Wechselkurs nicht abgerufen werden kann.\n *\n * @see \\PriceCalculator::applyDiscounts() Für Details zur Rabattberechnung.\n */\npublic function calculateFinalPrice(float $basePrice, float $taxRate, string $currency = 'RUB'): string\n{\n    if ($basePrice < 0) {\n        throw new \\InvalidArgumentException('Der Grundpreis darf nicht negativ sein.');\n    }\n    // ... Berechnungslogik\n}

Beachten Sie: Wir haben nicht nur die Typen aufgelistet, sondern auch den Kontext (progressive Staffel), das Format (formatierte Zeichenfolge) und die Randbedingungen (Ausnahmen) erklärt. Das ist qualitativ hochwertige Dokumentation.

Best Practices: Vom Einfachen zum Komplexen

1. Dokumentieren Sie die öffentliche API, lassen Sie private in Ruhe

Sie müssen nicht für jeden privaten Getter oder Setter einen PHPDoc schreiben. Die IDE sieht den Typ bereits. Konzentrieren Sie sich auf die öffentliche Schnittstelle Ihrer Klassen und Methoden – das, was andere Entwickler verwenden werden. Private Methoden sollten selbsterklärend sein; wenn nicht, ist das ein Zeichen dafür, dass Sie Ihren Code umgestalten sollten.

2. Beschreiben Sie das "Warum", nicht das "Wie"

Der Code selbst zeigt bereits, wie er funktioniert. Die Dokumentation sollte erklären, warum Sie sich für einen bestimmten Ansatz entschieden haben. Zum Beispiel:

/**\n * Verwendet einen Memoization-Cache, um wiederholte API-Aufrufe zu vermeiden.\n * Der Cache läuft nach 5 Minuten ab, um die Relevanz der Daten zu gewährleisten.\n */

Anstatt:

/**\n * Ruft die API auf und speichert das Ergebnis im Cache.\n */

3. Halten Sie die Dokumentation aktuell

Veraltete Dokumentation ist schlimmer als gar keine. Sie führt Entwickler in die Irre. Machen Sie es zur Gewohnheit, PHPDoc-Blöcke zu aktualisieren, wenn Sie den Code ändern. Verwenden Sie Tools wie PHPStan oder Psalm, die Inkonsistenzen zwischen Code und Dokumentation erkennen können.

4. Verwenden Sie Typdeklarationen

Moderne PHP-Versionen (7.0+) unterstützen Typdeklarationen für Parameter und Rückgabewerte. Nutzen Sie sie! Sie reduzieren die Menge an PHPDoc, die Sie schreiben müssen, und machen den Code sicherer.

// Statt:\n/** @param int $id */\npublic function getUser($id) { ... }\n\n// Verwenden Sie:\npublic function getUser(int $id): ?User { ... }

5. Dokumentieren Sie Ausnahmen gründlich

Jede Methode, die eine Ausnahme werfen kann, sollte dies mit @throws dokumentieren. Geben Sie an, unter welchen Bedingungen die Ausnahme geworfen wird. Dies hilft Entwicklern, Fehler ordnungsgemäß zu behandeln.

Tools zur Dokumentationsgenerierung

Sobald Ihr Code mit PHPDoc versehen ist, können Sie automatisch eine schöne Dokumentation generieren. Die beliebtesten Tools:

\n
• phpDocumentor — Der Klassiker. Erzeugt HTML-Dokumentation aus PHPDoc-Kommentaren.
\n
• Doxygen — Unterstützt mehrere Sprachen, einschließlich PHP. Gut geeignet für Projekte mit gemischten Technologien.
\n
• Sami — Modernes Tool mit schöner Ausgabe und Unterstützung für mehrere Versionen.
\n
• ApiGen — Einfach zu bedienen, aber nicht mehr aktiv entwickelt.
\n

Die meisten dieser Tools können in CI/CD-Pipelines integriert werden, um die Dokumentation bei jedem Build automatisch zu aktualisieren.

Fazit: Dokumentation ist eine Investition

Gute Dokumentation in PHP erfordert Zeit und Disziplin. Aber sie ist eine Investition, die sich schnell auszahlt: weniger Fehler, schnellere Einarbeitung, besserer Code. Fangen Sie noch heute an – dokumentieren Sie Ihre nächste Funktion mit PHPDoc. Ihr zukünftiges Ich (und Ihr Team) werden es Ihnen danken.

Denken Sie daran: Der beste Code ist der, den jeder verstehen kann. Und die beste Dokumentation ist die, die niemand braucht, weil der Code klar ist – aber das ist ein Ideal, dem wir uns nur durch gute Dokumentation annähern können.