Hauptmenü

Untermenü

PHP - Grundlagen - Programmierstile - Kommentare

1. Standards?

Gab es lange Zeit keine. Darum hat auch jeder gemacht was er/sie wollte. Mit dem Ergebnis, dass sich heutzutage viele Programmierer durch den eigenen oder fremden Ekelcode aus längst vergessenen Zeiten kämpfen müssen und keine Sau weiß, was wofür gebraucht wird. Gottlob hat sich mittlerweile ein Standard eingebürgert, die PEAR Coding Standards für Kommentare. Und die solltet ihr auf jeden Fall nutzen, da sie sehr gut aufgebaut sind. Der zusätzliche Vorteil dabei ist, dass man mit Programmen wie phpDocumentor automatisch Dokumentationen von seinem Quellcode erstellen kann, besonders wenn er objektorientiert programmiert wurde.

2. PEAR Coding Standards für Kommentare

Grundlagen

Einzeilige Kommentare fangen wie gehabt mit // an. Bei mehrzeiligen dagegen gibt es eine kleine Besonderheit. Sie beginnen mit einem /**, enden mit einem */ und die Kommentare werden dann dazwischen (!) in die einzelnen Zeilen geschrieben, die jeweils mit * anfangen. Also so:


<?php
 /**
  * Dies ist ein mehrzeiliger Kommentar,
  * der so aussehen sollte und nicht anders
  */
  function doSomething() ...
?>

Ich persönlich habe mir angewöhnt, das erste / um ein Leerzeichen nach links einzurücken, damit die Sternsken (*) schön untereinander und auf Höhe des folgenden Codes stehen. Auch nutze ich diese Schreibweise mittlerweile bei einzeiligen Kommentaren, da ich erstens nie weiß, ob da noch etwas hinzu kommt und ich zweitens großen Wert auf Einheitlichkeit lege. Bei solchen Dingen bin ich einfach sehr pedantisch.

Variablen

Der PEAR Standard sieht vor, dass Eigenschaften einer Klasse genauer beschrieben werden müssen. Das kann man auch auf die unsäglichen als global deklarierten Variablen in Funktionen übertragen. Ebenso besteht die Möglichkeit, bei prozeduraler Programmierung dies auch generell für global verfügbare Variablen zu nutzen. Dabei gibt es neben der eigentlichen Beschreibung ein paar "Schlüsselwörter" für weitere Informationen, die mit einem @ beginnen:


<?php
 /**
  * Hier wird der Sinn des Lebens definiert
  * @var int
  *
  * bei Eigenschaften von Klassen zusätzlich die Sichtbarkeit
  * @access public
  */
  public $meaning_of_life 42;
?>

Funktionen und Klassen

Da sich die PEAR Coding Standards für Kommentare hauptsächlich auf Klassen bezieht, übertrage ich das einfach auch mal auf Funktionen. Das ist zwar nicht ganz glücklich, ich mache es aber trotzdem, wie so oft ;-). Dabei sollte man so genau wie möglich die Aufgabe der Klasse/Funktion beschreiben. Dazu gehören eventuelle Parameter und Rückgabewerte.

Damit ihr euch ein Bild davon machen könnt, gibt es hier ein abschreckendes Beispiel meinerseits. Wer es ganz genau wissen will, sollte sich mal das oder das hier ansehen. Da wird genau beschrieben, wie man vorzugehen hat und was für zusätzliche "Schlüsselwörter" es noch gibt. Also die mit dem @ davor.

3. Die Sprache

Das ist so eine Sache. In international tätigen Unternehmen ist Englisch natürlich die Hauptsprache. Also sollte man in dem Fall auch in der Lage sein, seine Kommentare in dieser Sprache verfassen zu können. Ansonsten reicht in eurem Fall auch Deutsch aus. Das hat zum einen den Vorteil, dass euch eure Kollegen verstehen und zum anderen, dass im Falle eines geplanten IT-Outsourcing in andere Länder ihr ein Erpressungsmittel habt. Frei nach dem Motto:

"Eih, Alder von McKinsey. Du willst auslagern. Übersetzt du Kommentare selber." [Quelle: Erpresser mit Hirn]

Bei privaten Projekten könnt ihr natürlich jede Sprache nehmen, mit der ihr klar kommt. Selbst wenn es sich dabei um Kisuaheli oder Mandarin-Chinesisch handelt.

zurück zum vorherigen Abschnitt weiter zum nächsten Abschnitt