Coding-"Richtlinien"

Die auf dieser Seite aufgezählten "Richtlinien" sind natürlich keine strikte Vorgabe an Entwickler. Jeder Programmierer hat sich im Laufe der Zeit seinen eigenen Stil beim Programmieren angewöhnt. Ähnliche Strukturen helfen aber beim Lesen vom Code eines anderen Programmierers und vereinfachen das Verstehen und Bearbeiten ungemein.

Aus diesem Grund haben wir bei Bartels.Schöne uns ein paar Vorgaben gemacht. Diese basieren auf den Coding Standards des PHP Extension and Application Repository (PEAR):

Grundsätzlich gilt für diese Richtlinien aber das übliche: Ausnahmen bestätigen die Regel.

Einrücken und Zeilenlänge

  • Zum Einrücken werden 4 Spaces und keine Tabs benutzt.
  • Eine Zeile sollte nach 75-85 Zeichen umgebrochen werden (Balu: leider oft nicht möglich).

Superglobals

  • Wenn Werte an eine PHP-Seite übergeben werden, benutzen wir die "Superglobals" wie $_GET, $_POST, $_REQUEST, usw. um sie auszulesen.

Bedingungen

Die folgenden Regeln gelten für if, for, while, switch, usw..

  • Bedingungen haben vor der öffnenden Klammer immer ein Leerzeichen, damit man sie einfacher von Funktionsaufrufen unterscheiden kann.
  • Es sollten immer geschweifte Klammern verwendet werden, auch wenn sie nicht unbedingt nötig erscheinen. Dieses verhindert ansonsten sehr wahrscheinliche logische Fehler wenn neue Zeilen ergänzt werden und erhöht die Lesbarkeit des Codes.

Ein Beispiel für die if-Bedingung sieht wie folgt aus:

 <?php
 if ((condition1) || (condition2)) {
     action1;
 } elseif ((condition3) && (condition4)) {
     action2;
 } else {
     defaultaction;
 }
 ?>

Ein Beispiel für eine switch-Fallunterscheidung:

 <?php
 switch (condition) {
 case 1:
     action1;
     break;

 case 2:
     action2;
     break;

 default:
     defaultaction;
     break;
 }
 ?>

Funktionsaufrufe

  • Funktionen werden ohne Leerzeichen zwischen dem Funktionsnamen, der öffnenden Parameterklammer und dem ersten Parameter geschrieben.
  • Zwischen einem Komma und dem folgenden Parameter steht ein Leerzeichen.
  • Keine Leerzeichen stehen zwischen dem letzten Parameter, der schliessenden Klammer und dem ";"

Beispiel:

 <?php
 $var = foo($bar, $baz, $quux);
 ?>

Wertzuweisungen und Vergleiche

  • Wie man bei den Funktionsaufrufen sehen kann, steht bei einer Wertzuweisung mit "=" vor und nach dem "="-Symbol jeweils ein Leerzeichen.
  • Wenn mehrere Zuweisungen in einem Block durchführt, kann man mehr Leerzeichen einfügen, um die Lesbarkeit zu erhöhen:
 <?php
 $short         = foo($bar);
 $long_variable = foo($baz);
 ?>
  • Vergleichsoperationen werden ohne Leerzeichen geschrieben: "$a==1", "1>=2", usw.

Funktionsdefinitionen

  • Im Gegensatz zu den geschweiften Klammern bei Bedingungen, werden bei Funktions- und Klassendefinitionen die Klammern für sich alleine in eine Zeile geschrieben:
 <?php
 function fooFunction($arg1, $arg2 = '')
 {
     if (condition) {
         statement;
     }
     return $val;
 }
 ?>
  • Parameter mit Defaultwerten sollten am Ende der Parameterliste stehen.
  • (Eine Funktion sollte nach Möglichkeit immer einen sinnvollen Wert zurückliefern.)

Kommentare

Eine der Grundregeln beim Programmieren ist: Lieber zu viele, als zu wenige Kommentare. Wenn man sich ein Codestück anschaut und denkt "Wow, das möchte ich lieber nicht beschreiben." sollte man so schnell wie möglich Kommentare einfügen, bevor man vergessen hat, was dort passiert.

  • Für Kommentare werden die C ("/* foobar */") und C++ ("// foobar") Varianten genommen. Die aus Perl oder der Shell bekannten Kommentare ("# foobar") sollten vermieden werden.

Einbinden von Code

(Balu: Beschreibung fehlt, wann require_once(), include_once(), require() oder include() benutzt werden sollten.)

  • include_once und require_once sind keine Funktionen und werden deswegen ohne Klammern um den Dateinamen geschrieben. (Balu: Diese Regel haben wir bisher ignoriert :))

PHP-Code-Tags

  • Es werden immer die langen PHP-Code-Tags "<?php ?>" benutzt, um PHP-Code einzubinden. Die Kurzform "<? ?>" ist nicht erlaubt, da diese auf unterschiedlichen Systemen schnell zu Problemen führt.

!! Header-Kommentarblock (noch nicht festgelegt)

!! Versionierungssystem CVS / SVN (noch(?) nicht öffentlich zugänglich)

Beispiel-Links

  • Beispiel-Links sollten immer auf example.com, example.org oder example.net zeigen, wie es der RFC 2606 vorschlägt.

Namens-Konventionen

(Balu: Ohje, bisher kaum berücksichtigt)

  • Klassennamen sollten beschreibende Namen haben, keine Abkürzungen.
  • Klassennamen beginnen mit einem Großbuchstaben.

* (Pear gibt noch vor, dass die Klassennamen die Hierarchie darstellen sollen

  • Funktionen und Methoden benutzen die "KamelWort"-Variante, bei der jedes Teilwort mit einem großen Buchstaben beginnt: "doSomethingSpecial()". Es werden keine Unterstriche als Trennzeichen benutzt.
  • Global verfügbare Funktionen und Methoden sollten mit einem eindeutigen Bezeichner wie einem Modulnamen anfangen, um Konflikte zwischen unterschiedlichen Modulen zu vermeiden. Dieser Bezeichner wird durch ein "_" vom Funktionsnamen getrennt: "cpo_doSomethingSpecial()".
  • Private Klassenfunktionen beginnen mit einem Unterstrich: "_private()"
  • Konstanten werden immer in Großbuchstaben geschrieben. Teilwörter werden durch Unterstriche getrennt: "EINE_KONSTANTE". Es ist sinnvoll, einer Konstanten den Modulnamen plus Unterstrich voranzustellen.
  • Ausnahmen gelten für die PHP-Konstanten true, false und null. Diese werden immer klein geschrieben.

* globale Variablen beginnen mit einem Unterstrich, dem Paketnamen und wieder einem Unterstrich.

Dateiformate

  • Dateien werden als ASCII-Text mit der Zeichenkodierung ISO-8859-1 gespeichert.
  • Dateien haben nach Möglichkeit das Unix-Format. Das bedeutet, das Zeilenende ist ein Linefeed (LF), nicht ein Carriage Return (CR) wie im Macintosh-Format und nicht die Kombination (CRLF) wie im Windows-Format.