PHP-Programmierung mit Stil - Teil III

Optionen kommen zum Schluss: Bei PHP-Funktionen kann man ja eine Liste der Übergabeparameter definieren. Aber auch hier sollte man nicht einfach drauflos schreiben.

Die beiden angezeigten Funktionen sind syntaktisch richtig - aber welche ist besser lesbar?

//Variante A
function verbrauch($kwH, $monat, $jahr=2009, $preis=0.234, $geb=25.79) {

//Variante B
function verbrauch($preis=0.234, $geb=25.79, $kwH, $jahr=2009, $monat) {

Ihre Antwort lautet sicher: Variante A. Auch ich bevorzuge diese Art der Reihenfolge: Alle Argumente mit einem Standardwert werden am Ende aufgereiht. Sie sehen, ich habe auch die Leerzeichen weggelassen, da dadurch die Zusammengehörigkeit des Tupels (Parameter-Werte-Paar) besser zum Ausdruck kommt. Wieso reiht man diese Art der Parameter jetzt an das Ende der Liste?

Viele Programmiersprachen kennen sogenannte optionale Parameter und können diese auch explizit definieren, aber PHP nicht. In dieser Sprache ist prinzipiell keins der Argumente einer Funktion ein Pflichtfeld. Es hängt nur von Ihnen als Programmierer ab, ob die Funktion mit einem Fehler reagiert oder nicht. Aber wenn Sie Argumente mit Standardwerten vorbelegen, können Sie sie beim Aufruf der Funktion weglassen und trotzdem den Basiswert innerhalb der Funktion verwenden.

Was gehört wohin?

Wir programmieren ja so, dass wir Funktionen, die wir öfter brauchen in eigene Dateien auslagern. Genauso hat jede Datei selbst definierte Variablen und Funktionen. Gewöhnen Sie es sich an, diese immer in derselben Abfolge in die Datei zu schreiben. Ich mache nach dem Kommentarblock folgendes:

Externe Dateien, die eingebunden werden
Definition der Konstanten
Definition der Variablen
Sourcecode außerhalb von Funktionen
globale Funktionen
Hilfsfunktionen für Punkt 5

Kein Programm ohne Kommentar!

Wenn Sie noch nicht so viel programmiert haben, werden Sie sich vielleicht denken: Was soll denn das? Ich verstehe doch, was ich programmiere und brauche es nicht mehr zu erklären! Ja, jetzt verstehen Sie es, aber wie schaut es in zwei Wochen, zwei Monaten oder einem Jahr aus? Werden Sie dann noch immer alle Routinen und Befehlssequenzen kennen oder müssen Sie sich wieder „neu hineindenken"? Wahrscheinlich letzteres und das wird Sie mit der Zeit ziemlich nerven.

Wenn Sie mit einem Tool wie phpDocumentor arbeiten, sind Sie so oder so gezwungen, eine gewisse Struktur der Kommentare einzuhalten. Falls nicht, sollten Sie sich ein ähnliches oder ein an Ihre Bedürfnisse angepasstes Schema überlegen und konsequent anwenden. Wenn Sie viel programmieren oder vorhaben, Programmierer zu werden, werden Sie über kurz oder lang ein Tool einsetzen. Warum also nicht gleich?

Vielleicht haben Sie im Teil II dieses Tutorials bemerkt, dass ich beim schließenden Blockoperator auch einen Kommentar angefügt habe. Es ist einfach praktisch, denn man sieht sofort, zu welcher öffnenden Klammer diese einsame, allein dastehende schließende Klammer gehört. Gerade bei langen Blöcken, die über eine Bildschirmseite gehen, sparen Sie mit dieser Praxis viel Hin- und Herscrollen im Sourcecode. Hier ein Beispiel für einen langen Kopfkommentar einer Datei:

Ganzen Artikel lesen...

/*****
* Hier steht eine kurze Beschreibung der Datei
*
* Dies hier wird die lange Beschreibung der Datei. Dies koennen mehrere
* Zeilen sein. Sie kann aber auch weggelassen werden, falls die Funktion
* in der Kurzbeschreibung klar ausgedrueckt wurde.
*
* PHP versions 4 and 5
*
* LIZENZ: Hier kommt die Lizenz unter welcher diese Datei liegt.
* Idealerweise wird hier auch eine URL zur Linzenz angegeben.
*
* @category Kategorie
* @author Urspruenglicher Autor <autor@example.com>
* @author Anderer Autor <another@example.com>
* @copyright 2008 - 2009, Autor Name
* @version Major.Minor, Datum, Uhrzeit
*
* @todo Falls noch Aufgaben in dieser Datei zu erledigen sind, kann man
* sie hier beschreiben.
*/

Auch jede Funktion, jede Klasse u.s.w. sollte dokumentiert werden. Ich verwende dazu auch das Schema von phpDocumentor. Im Beispiel unten zeige ich, wie es wirklich aussehen kann. Ich verwende wieder nicht alles, was phpDocumentor anbietet, sondern ausschließlich das, was für mich praktikabel und sinnvoll ist.

/*****
* Berechnet die Kostens des Verbrauchs
*
* Dies Funktion berechnet aus den Uebergabewerten die Kosten des
* Verbrauchs. Optional kann der Wert auch noch formatiert werden.
*
* @version Major.Minor, Datum, Uhrzeit
*
* @param float $verbrauch verbrauchte Menge
* @param float $preis Kosten pro Einheit in Euro
* Bestenfalls auf zwei Nachkommastellen
* @param boolean $format wird die Zahl formatiert
* es wird das deutsche Zahlenformat
* angewendet
*
* @return mixed Kosten des Verbrauchs als float (unformatiert),
* als string (formatiert)
*
* @uses $varName welche globale Variable wird warum benutzt
*/
function foo($verbrauch, $preis=1.23, $format=false) {
$retValue = ""; //Rueckgabewert
$retValue = $verbrauch * $preis;
if ($format) {
$retValue = number_format($retValue, 2, ",", ".");
}
return $retValue;
}

Falls Sie keine klingenden Variablennamen verwenden wollen oder können, dann dokumentieren Sie sie gleich in derselben Zeile. Dann brauchen Sie später nicht zu suchen, wo Sie sie dokumentiert haben.

Fazit

Dies sind keine unumstößlichen Gesetze und auch nicht der Weisheit letzter Schluss, sondern Erfahrungen aus mehr als zwei Jahrzehnten Programmierung in den verschiedensten Sprachen und aus der Lehrerfahrung für andere Programmierer. Ich habe über die Jahre bemerkt, dass jeder Programmierer wie ein Künstler seinen eigenen Stil entwickelt. Man kann Sourcecode wie Poesie lesen. Und man spürt und sieht wirklich den Menschen dahinter!

Die passende Ergänzung zu diesem Artikel: