Syntaxnorm - 10 einfache Regeln

Mal ganz vom Anfang an

Im Jahre 1999 gründete ein Herr namens Malin Bakken das PEAR Rahmennetzwerk. Schnell erklärt, handelt es sich dabei um eine Sammlung von OpenSource PHP-Skriptas, an denen sich jeder beteiligen kann und die jeder verwenden darf. Im Internet unter pear.php.net zu finden.

Wenn da aber nun tausende Leute an den Skripten herumpfuschen, wird bald klar, dass man eine einheitliche Darstellungsform benötigt, sodass sich nicht jeder, der ein fremdes Skript bearbeiten will erstmal daran gewöhnen muss wie der andere seinen Quelltext formatiert. Die PEAR hat daher sehr früh eine einfache Norm herausgebracht, an die sich so ziemlich alle großen öffentlichen Quelltext-Anbieter halten.

Die offizielle PHP-Doku auf php.net hält sich auch daran und auch hier in WS überarbeiten wir alle Tutorien um sie dieser Norm anzugleichen - der Norm der PEAR Coding Standards.

Die Regeln

1. Benutz 4 Leerzeichen um deinen Quelltext einzurücken, verwende nach Möglichkeit keine Tabs.

2. if, else, elseif, switch, while, for, foreach usw. sind Strukturen keine Funktionen. Zwischen ihnen und ihren Bedingungen wird ein Leerzeichen hinzugefügt um sie optisch von Funktionen zu trennen. Die geschwungen Klammern werden wie im folgenden Beispiel notiert:
<?php
if ((bedingung1) || (bedingung2)) {
action1;
} elseif ((bedingung3) && (bedingung4)) {
action2;
} else {
standardaktion;
}
?>

Die erste Geschwungene kommt noch in der selben Zeile, die letzte erhält eine eigene. Kommt eine Zusatzbedingung dazu, erfolgt diese in der selben Zeile wie die geschwungene letzte Klammer der vorhergehenden (also zum Beipiel "} else {"). Der Inhalt der Bedingungen wird um 4 Leerzeichen eingerückt.

Man soll außerdem auf Kurzschreibweisen verzichten und immer geschwungene Klammern setzen, auch wenn diese unnotwendig sind, um die Lesbarkeit zu erhöhen und weil das erfahrungsgemäß logischen Fehlern beim Lesen fremden Quelltextes vorbeugt.

Innerhalb der Bedingungen soll man AND, OR usw nicht ausschreiben, sondern die && und || Zeichenschreibweise verwenden.

Die switch sieht so aus:
<?php
switch (bedingung) {
case 1:
aktion1;
break;

case 2:
aktion2;
break;

default:
standardaktion;
break;
}
?>


4. Funktionsaufrufe sollen keine Leerzeichen zwischen dem Namen der Funktion und den Bedingungen haben um sie optisch von den Strukturen (if, for usw.) zu trennen. Die Parameter der Bedingunen sollen mit Leerzeichen optisch voneinander getrennt werden:
<?php
$var = funktion($para1, $para2, $para3);
?>

5. Variabeln sondern der Übersichtlichkeit wegen - wenn sie in großen Listen untereinander notiert werden - am Gleichzeichen ausgerichtet werden:
<?php
$kurz = foo($bar);
$lange_variabel = foo($baz);
?>

6. Funktions-Deklarationen sollen dem folgenden Schema entsprechen:
<?php
function testFunktion($arg1, $arg2 = '')
{
if (bedingung) {
quelltext;
}
return $wert;
}
?>

7. Dein Skript sollte eine möglichst durchgehende Kommentierung haben. Also alle möglichen Schritte mit //erklären und im Kopf der Datei mit /**/ eine kurze, übersichtliche Erklärung haben was das Skript macht. Die raute (#) soll man nicht verwenden zumKommentieren.

8. Inkludieren. Der include ist keine Funktion sondern ein Kommando. Er erhält deswegen keine runden Klammern! Außerdem verwende nicht den include sondern include_once und require_once um Dateien einzubinden und zu verhinden dass dies ungewollt mehrmals passiert.

9. Verwende bei den PHP-Tags die ausführliche Schreibweise (<?php ?>) nicht die kurze (<? ?>), das könnte bei der Kompabilität mit anderen Systemen Probleme bereiten.

10. Eigene Funktionsnamen sollen keine Unterstriche haben sondern Teilworte optisch durch Großschreibung trennen. Zum Beispiel: meineGuteFunktion.

Kommentare

Chefkoch
Chefkoch am Donnerstag, 14. September 2006 um 22:52

Aunschaulich und verständlich zusammengefasst! Sollten sich einige Coder wirklich mal zu Herzen nehmen. Selbst wenn man nur zu zweit oder dritt an einem Projekt arbeitet und der andere sich nicht an diese Grundregeln hält wird es schon kompliziert. Auch wenn man nachträglich mal was an seinem Code ändern möchte its es einfacher sich wieder die Sachen klar zu machen.

Einziger Punkt den ich noch nicht kannte war der fünfte. Das dargestellte Beispiel hat für mich auch nicht ganz gezeigt was ich aus der Beschreibung verstanden habe. Dazu vielleicht noch eine kleine Erklärung?

Markus René Einicher
Markus René Einicher am Freitag, 15. September 2006 um 19:30

Jetzt passts in der fünften, hab mich bei den Leerzeichen verzählt, jetzt sind die Werte der Variabeln schön untereinander, also an den Gleichzeichen ausgerichtet in einer Spalte.

Apple
Apple am Montag, 18. September 2006 um 10:07

ad2.) In meinen Augen ist
}
else
{
übersichtlicher und deshalb halte ich mich hierbei nicht daran. Ansonsten sind es wie gesagt Grundregeln an die man sich halten sollte, aber nicht muss.

@chefkoch: Es geht bei Punkt 5 nur um die übersichtlichkeit! Die Werte der Variable beginnen immer an dem gleichen Punkt. Somit stehen sie untereinander - der Beispielcode zeigt das eigentlich sehr schön.

Markus René Einicher
Markus René Einicher am Montag, 18. September 2006 um 10:10

Ich fands so auch anfangs übersichtlicher. Mittlerweile aber hat mich die komapte Schreibweise überzeugt, weil das dann so in die Länge gezogen aussieht und das nervt bei langen Skripts noch zusätzlich.

muuhmann
muuhmann am Montag, 25. September 2006 um 16:39

wieso sollte man keinen tabs verwenden, sondern 4 leerzeichen? Das wusste ich bis jetzt nicht..

@easterdom: je ausführlicher die kommentierung und übersichtlicher der code, desto weniger wartungsarbeit für dich.. ich hoffe für dich, du meinst mit kompakte schreibweise nicht die short_tags sondern sowas wie ($a = true) ? echo("a"); : echo("b");

Markus René Einicher
Markus René Einicher am Dienstag, 26. September 2006 um 09:17

Die Tabs haben damit zu tun, dass diverse Editoren das unterschiedlich interpretieren, manche gar nicht.

Ja das Letztere ist gemeint, keine Kurzschreibweisen.
Short-Tags braucht eh keiner, kein normaler Progger tu heutzutage noch den HTML-Quelltext direkt in den Code. Höchstens wenns schnell schnell gehn muss.