2
Bessere Kommentare für eure PHP-Skripte
PHP-Programmier sein wollen viele – doch nur weil man es geschafft hat erfolgreich in seinem WordPress-Temlate seine Besucher mit Namen zu grüßen heißt nicht, dass gut darin ist.
Als professioneller PHP-Programmier erlebe ich eine Geringschätzung gegenüber PHP, die sich bei genauerer Betrachtung oftmals nur als Unwissen oder Unfähigkeit herausstellt.
Nicht zuletzt liegt der schlechte Ruf von PHP sicher auch darin verwurzelt, dass man sehr unsauber damit programmieren kann und oft kräuseln sich einem beim lesen fremden Codes die Zehennägel.
In meiner neuen Kategorie PHP 5, möchte ich euch Tipps und Kniffe zeigen, mit denen man seinen eigenen Programmierstyl verbessern kann. Ob und was man von meinen Ratschlägen übernimmt, sei einem selbst überlasssen.
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 Klein auf damit beginnen auf vernünftige Kommentare zu achten.
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
Achtung: 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.
Bis zum nächsten mal
Bis zum nächsten mal, bis dahin: Vielleicht habt ihr ja Lust eure Kommentargewohnheiten zu ändern.
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…
@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.