Bessere Kommentare für eure PHP-Skripte 6


Als PHP-Programmier erlebe ich häufig eine Geringschätzung gegenüber PHP, die sich bei genauerer Betrachtung oftmals als Unwissen oder Unfähigkeit herausstellt.

Möglicherweise ist der schlechte Ruf von PHP sicher darin verwurzelt, dass man sehr unsauber damit programmieren kann und oft kräuseln sich einem beim lesen von Codefragmenten die Zehennägel.

In meiner neuen Kategorie PHP 5 möchte ich euch ein paar Kniffe zeigen, mit denen man seinen eigenen Programmierstyl verbessern kann. Inwiefern diese Ratschläge nützlich sind, sei dem Leser überlassen.

Heute geht es um das leidige Thema Kommentare.

Warum sind Kommentare wichtig?

Bei YiGG haben wir im laufe der Zeit viele zehntausend Zeilen Quellcode erzeugt. Wir sind ein kleines Team und jeder von uns hat einen Großteil des Codes schon einmal gesehen. Würden wir nicht akribisch auf die Dokumentation des Codes achten, hätten wir schnell einen echtes Problem und würden Stunden damit verbringen herauszufinden, was Funktion xyz genau macht.

Writing good documentation is essential to the success of any software project. The quality of documentation can be even more important than the quality of the code itself, as a good first impression will prompt developers to look further into your code.

Um ein guter PHP-Entwickler zu werden, sollte man also gleich von Anfang an darauf achten, vernünftige Kommentare zu schreiben.

Industriestandard phpDocumentor

Es empfiehlt sich für seine Kommentare ein einheitliches Format zu verwenden, dass von jedem anderen professionellen PHP-Programmierer verstanden wird.

In der PHP-Welt hat sich in den letzten Jahren zusehends das phpDocumentor-Format durchgesetzt. Es hat den großen Vorteil, dass die Dokumentation nicht nur gut für Menschen sondern auch gut durch Maschinen lesbar ist. Konkret bedeutet das: Wer seine Dokumentation mit phpDocumentor schreibt, wird auch in allen IDE’s später den Komfort der Autocompletion für seinen eigenen Code genießen können.

Ein weiterer Vorteil ist das man mit phpDocumentor auch eine komplette und klickbare Dokumentation all seiner Klassen und Funktionen erstellen lassen kann

Aber lassen wir kurz mal den Code sprechen, damit ihr am Beispiel einer Datei aus einem beliebigen großen PHP-Projekt mal sehen könnt wie so etwas aussieht.

< ?php
/**
 * Piwik - Open source web analytics
 *
 * @link http://piwik.org
 * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
 * @version $Id: Auth.php 581 2008-07-27 23:07:52Z matt $
 *
 * @package Piwik
 */

interface Piwik_Auth {
	/**
	 * @return Piwik_Auth_Result
	 */
	public function authenticate();
}

/**
 *
 * @package Piwik
 */
class Piwik_Auth_Result extends Zend_Auth_Result

Sowohl jede Datei, als auch jede Klasse und Funktion werden dokumentiert. Die Tags sind dabei genau festgelegt. Als Einstieg empfiehlt es sich folgendes Cheatsheet von 2tbsb.com herunterzuladen. Es lohnt sich, das PDF auszudrucken und immer in Sichtweite zu haben, bis man die wichtigsten Tags verinnerlicht hat.

Nützlich können ausserdem IDE's sein, die die phpDocumentor-Tags automatisch ergänzen.

Sonstige Konventionen

Oft benutz und auch von vielen IDEs erkannt werden auch Kommentare wie:
//@todo Eine bessere Lösung finden

Man kann auch zu viel kommentieren!

Leider sieht man manchmal auch Dateien mit zu vielen Kommentaren - Trivialitäten sollten nicht kommentiert werden. Auch wenn sich das einfach anhört, aber zumindest ich habe am Anfang zu viel kommentiert und auch das macht den Code unübersichtlich.

Die Oftmals bessere Lösung ist z.b. das vergeben besserer Variablennamen oder das extrahieren einer Methode, die einen logischen Namen hat.

Der Code sollte an sich kommunizieren, was er tut. Solltet ihr also innerhalb einer Funktion den Drang verspüren zu kommentieren, lohnt es sich eine Sekunde innezuhalten und zu überlegen - kann ich das eleganter lösen? Sollte ich ein refactoring anwenden? Ist die Funktion zu lang? Meistens lautet die Antwort, dass man lieber nachpolieren sollte.

Wie haltet ihr es mit Kommentaren?


Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.

6 Gedanken zu “Bessere Kommentare für eure PHP-Skripte

  • Quix0r

    Interfaces sollen mit „able“ enden. Keinen Unterscore! Sondern so z.B. Throwable, Serializeable. Und Doxygen macht schoenere Doku, auch aus PHP-Code! 🙂 Beispiel hier: http://docs.ship-simu.org

    Das mit den Underscores in Methoden-, Klassen und Interface-Namen ist auch so eine „Unsauberheit“ die in PHP vorherrscht. Bitte mich nicht falsch verstehen. Ich programmiere unheimlich gerne PHP, mache aber seit einigen Monaten es anders, und zwar komplett OOP und alles schoen nach Kamelschreibweise, bzw. ungarische… 😉

  • Rocu

    @Quix0r Das ist ja nun Code aus Piwik (nicht mein eigener) und es ging mir eher darum das Augenmerk auf die Kommentare zu legen 🙂

    Underscores in Methoden und Klassennamen sind meiner Ansicht nach ok solange man ein System befolgt.

  • Noeppes

    …und wenn ich sehe wie viele Rechtschreibfehler die selbsternannten PHP-Profis der deutschen Sprache in deren Blogs antun…

    Bevor man mit seinen Fingern auf andere zeigt sollte man doch schon dafür sorgen das man sich richtig und möglichst fehlerfrei außern kann. Auch für die deutsche Rechtschreibung gibt es Regeln.

  • Robert Curth

    Im Rückblick sicher nicht einer meiner besten Artikel. Ich war damals noch nicht gut genug, um meine eigene Unfähigkeit gut einschätzen zu können.

    Bevor Du andererseits über meine Orthografie herziehst – erkläre mir doch bitte was „außern“ heißt 🙂

  • Noeppes

    So böse war es aber nicht gemeint.
    Natürlich mache auch ich Fehler.
    Was ist denn bitte ein „lieber Troll“? Aber egal.

    Sinnvolle Kommentare sind nur ein Teil des Scripts. Sinnvolle Namensgebung für Konstanten, Variablen, Funktionen, Klassen, Objekte… ist mindestens genauso wichtig.
    Ich befasse mich erst seit einigen Monaten intensiv mit PHP/HTML/CSS… und vermisse eine mehr oder weniger verbindliche Form. Besonders die Namensgebung ist oftmals bei fremden Scripten eine Herausforderung.
    Kommt denn mal ein Artikel mit dem du deine Vorgehensweise darlegst? Hier habe ich bisher nichts gefunden.
    Den phpDocumentor werde ich mir dahingehend aber auch ansehen.

    Bis dann
    Der „liebe Troll“

  • Robert Curth

    Das ist denke ich nur falsch angekommen – ich habe den Artikel gestern Abend etwas überarbeitet, da ich Dir vollkommen recht geben muss – er war schon ziemlich merkwürdig und überheblich geschrieben.

    Wahrscheinlich muss ich damals irgendwann gemerkt haben, dass mir nichts weiter einfällt und auf absenden gedrückt haben.

    Ich habe da tatsächlich ein paar Tricks auf Lager, was Namen angeht – allerdings die meisten schamlos geklaut aus „Robert Martin’s“ Clean Code (das ich dir übrigens unbedingt als Lektüre empfehle, falls Du noch keinen Blick hineingeworfen hast)