Programmier Richtlinien für phpBB Anmerkungen oder Vorschläge? E-Mail an ??? Editor Einstellungen Konventionen der Namensgebung Code Layout Grundsätzlich Richtlinien -------------------------------------------------------------------------------- 1. Editor Einstellungen Tabulator gegen Leerzeichen: Um das ganze so einfach wie möglich zu machen benutzen wir Tabulator-Schritte und keine Leerzeichen. Du kannst Dir aussuchen wie viele Leerschritte Dein Editor pro Tab benutzt. Stelle jedoch sicher, dass Dein Editor die Tabulator-Schritte speichert und nicht die Leerzeichen. So kann sich jeder den Code so anzeigen lassen, wie er es gerne hätte, ohne das aktuelle Layout der Datei zu zerstören. Zeilenvorschübe: Stelle sicher, dass Dein Editor die Dateien im UNIX-Format speichert. Das heißt, dass Zeilen mit einer neuen Zeile beendet werden und nicht mit einer CR/LF Kombination, wie es unter Win32 gemacht wird, oder was auch immer ein MAC benutzen mag. Einige gute Win32-Editoren sollten das können, es wird aber nicht immer die Standart-Einstellung sein. Lerne Deinen Editor kennen! Wenn Du Ratschläge zu einem Win32-Editor brauchst, frage einfach einen der Entwickler. Einige von Ihnen Benutzen einen Editor unter Win32. Top 2. Konventionen der Namensgebung Wir werden keinerlei Form von ungarischer Bezeichnung in unserer Namensgebung benutzen. Viele von uns glauben, dass ungarische Namen eine der Irrungen ist, die momentan gebräuchlich sind. (Chaze <-- Ergibt irgendwie keinen Sinn :-| ) Namen von Variablen: Alle Namen von Variablen sollten klein geschrieben werden. Eine Worttrennung wird durch einen Unterstrich gekennzeichnet. Beispiel: Richtig: $current_user Falsch: $currentuser oder $currentUser Namen sollten beschreibend sein aber trotzdem kurz. Wir wollen keinen langen Satz als Variablen Namen. Aber ein paar Zeichen mehr sind immer besser als sich später zu wundern für was diese Variable denn nun steht. Schleifen Index: Die Einzige Situation in dem der Variablen-Namen aus nur einem einzigen Buchstaben erlaubt ist, ist wenn es der Index für ein Schleifen Konstrukt ist. In diesem Fall sollte der Index einer äußeren Schleife immer $i heißen. Bei einer Schleifen innerhalb einer Schleife sollte er $j heißen, dann $k, usw. Wenn die Schleife durch eine bereits existierende Variable mit einem bedeutungsvollen Namen indiziert werden soll, greift diese Regel nicht. Beispiel: for ($i = 0; $i < $outer_size; $i++) { for ($j = 0; $j < $inner_size; $j++) { foo($i, $j); } } Namen von Funktionen: Namen von Funktionen sollten ebenfalls beschreibend sein. Wir programmieren hier nicht in C und wollen keine Funktionen schreiben, die z.B. "stristr()" heißen. Auch hier benutzen wir nur kleingeschriebene Namen und trennen Worte wieder durch einen Unterstrich. Namen von Funktionen sollten möglichst ein Verb beinhalten. Beispiele für gute Funktions-Namen wären print_login_status(), get_user_data(), etc. Funktions-Argumente: Argumente unterliegen denselben Richtlinien wie die Variablen-Namen. Wir wollen kein Bündel von Funktionen wie: mach_was($a, $b, $c) oder do_stuff($a, $b, $c). In den meisten Fällen wollen wir eine Funktion erklären können indem wir einfach deren Deklaration anschauen. Zusammenfassung: Die Grundlegende Philosophie ist einfach nicht die Klarheit eines Codes durch Faulheit zu zerstören. Es muss sich die Waage mit dem allgemeinen Empfinden halten. Wobei print_login_status_for_a_given_user() zu weit gehen würde. Diese Funktion sollte z.B. besser print_user_login_status() oder einfach nur print_login_status() genannt werden. Top 3. Code Layout Standart-Header für neue Dateien Hier ist eine Vorlage von dem Header, welcher am Anfang aller neuer Dateien eingefügt werden muss: /*************************************************************************** filename.php ------------------- begin : Sat June 17 2000 copyright : (C) 2000 The phpBB Group email : support@phpBB.com $Id: $ ***************************************************************************/ /*************************************************************************** * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * ***************************************************************************/ Füge immer die (geschweiften) Klammern ein. Ein anderer von Fall Faulheit ist, wenn das Einfügen von 2 zusätzliche Zeichen zu viel ist, was der Verständlichkeit des Codes schadet. Selbst wenn der Körper eines Konstrukts nur eine Zeile lang ist, solltest Du die (geschweiften) Klammern nicht weglassen. Beispiele: /* Dies ist alles Falsch. */ if (condition) do_stuff(); if (condition) do_stuff(); while (condition) do_stuff(); for ($i = 0; $i < size; $i++) do_stuff($i); /* Und dies ist alles Richtig. */ if (condition) { do_stuff(); } while (condition) { do_stuff(); } for ($i = 0; $i < size; $i++) { do_stuff(); } Wo sind die Klammern zu setzen: Die gleicht ein bisschen einem heiligen Krieg aber wir benutzen einen Stil welcher in zwei Sätzen zusammen gefasst werden kann: Klammern stehen immer in einer eigenen Reihe. Die schließende Klammer sollte immer in der gleichen Spalte wie die entsprechende eröffnende Klammer stehen. Beispiele: if (condition) { while (condition2) { ... } } else { ... } for ($i = 0; $i < $size; $i++) { ... } while (condition) { ... } function do_stuff() { ... } Benutze Leerzeichen zwischen den Zeichen: Dies ist ein anderer einfacher Schritt um den Code ohne großen Aufwand lesbar zu halten. Immer wenn Du eine Aufgabe, Ausdruck, etc. schreibst, setze immer ein Leerzeichen zwischen die Zeichen. Schreibe Code grundsätzlich so als wäre er in deiner Muttersprache. Setze Leerzeichen zwischen Variablen-Namen und Operatoren. Setze bloß keine Leerzeichen nach einer eröffnenden Klammer oder vor eine schließende Klammer. Setze bloß keine Leerzeichen vor einem Komma oder vor einem Semikolon. Dies lässt sich am besten anhand einiger Beispiele verdeutlichen: /* Jedes Paar zeigt ein falsches gefolgt von einem richtigen Beispiel. */ $i=0; $i = 0; if($i<7) ... if ($i < 7) ... if ( ($i < 7)&&($j > 8) ) ... if (($i < 7) && ($j > 8)) ... do_stuff( $i, "foo", $b ); do_stuff($i, "foo", $b); for($i=0; $i<$size; $i++) ... for($i = 0; $i < $size; $i++) ... $i=($j < $size)?0:1; $i = ($j < $size) ? 0 : 1; Operatoren Priorität: Kennst Du ganz genau die Prioritäten von allen Operatoren in PHP? Ich tue es nicht. Rate nicht. Mach die Priorität einer Gleichung durch die Verwendung von Klammern immer offensichtlich, so dass Du weißt was passiert. Beispiele: /* Wie ist das Ergebnis? Wer weiß... */ $bool = ($i < 7 && $j > 8 || $k == 4); /* Hier kannst Du Dir sicher sein was ich mache. */ $bool = (($i < 7) && (($j < 8) || ($k == 4))) Layout einer SQL-Anweisung: Da wir alle verschiedene Editor-Einstellungen benutzen versuche nicht irgendwas kompliziertes, wie das anordnen von Spalten, in einer SQL-Anweisung zu machen. Schreibe Anweisungen immer in eine eigene Reihe. Hier ist ein Beispiel, wie SQL_Anweisungen aussehen sollten. Beachte die Zeilenumbrüche, die Großschreibung und die Verwendung von Klammern: SELECT field1 AS something, field2, field3 FROM table a, table b WHERE (this = that) AND (this2 = that2) Top 4. Grundsätzliche Richtlinien Anführungszeichen von Strings: Es gibt in PHP zwei Möglichkeiten Strings in Anführungszeichen zu setzen. Zu einem mit einfachem (') und zu anderen mit doppeltem (") Anführungszeichen. Der hauptsächliche Unterschied ist, dass der Parser in Strings, die mit doppeltem Anführungszeichen eingeleitet wurden, angegebene Variablen-Namen als Text ausgibt und als den Wert der Variablen. Aus diesem Grunde solltest Du immer einfache Anführungszeichen verwenden, außer Du willst explizit den Variablen-Name als Text in einem String ausgeben. So können wir dem Parser die Arbeit sparen Strings zu parsen wo keine Interpolation nötig ist. Wenn Du eine String Variable als ein Teil eines Funktions-Aufrufes benutzt, brauchst Du diese Variable nicht in Anführungszeichen zu setzen. Noch mal: Dies würde dem Parser nur unnötige Arbeit bereiten. Bedenke jedoch, dass fast alle Escape Sequenzen, welche für in doppelte Anführungszeichen gesetzte Strings existieren, nicht in Strings, die in einfache Anführungszeichen gesetzt sind, funktionieren. Sei sorgfältig und fühl Dich frei diese Richtlinie zu brechen, wenn diese Deinen Code schwerer zu lesen macht. Beispiele: /* Falsch */ $str = "This is a really long string with no variables for the parser to find."; do_stuff("$str"); /* Richtig */ $str = 'This is a really long string with no variables for the parser to find.'; do_stuff($str); Assoziative Array Schlüssel: In PHP ist es erlaubt literale Strings als einen Schlüssel zu einem assoziative Array zu verwenden, ohne diesen String in Anführungszeichen zu setzen. Das wollen wir aber so nicht machen. Der String sollte immer in Anführungszeichen gesetzt werden um Verwirrungen zu vermeiden. Bedenke, dass dies nur bei literalen Strings gilt, nicht wenn Du eine Variable benutzt. Beispiele: /* Falsch */ $foo = $assoc_array[blah]; /* Richtig */ $foo = $assoc_array['blah']; Kommentare: Jeder Funktion sollte ein Kommentar vorausgehen die einem Programmierer alles, was er über diese Funktion wissen muss um sie zu benutzen, erklärt. Die Bedeutung eines jeden Parameters, die erwarteten Eingaben und die erwarteten Ausgaben sollten in einem möglichst kurzen Kommentar beschrieben sein. Das Verhalten der Funktion bei Fehlern (und welche Fehler das sein könnten) sollte ebenfalls beschrieben sein. Niemand sollte sich die eigentliche Quelle einer Funktion anschauen müssen um sie mit Zuversicht in seinem eigenen Code aufrufen zu können. Außerdem sollten wir selbstverständlich alles trickreiche, obskure oder jeden sonst nicht sofort ersichtlichen Code beschreiben. Im speziellen sollten alle Annahmen die Dein Code erlaubt oder die Bedingungen die er für seine sichere Ausführung benötigt dokumentiert werden. Alle Entwickler sollten in der Lage sein jeden Teil der Anwendung anzuschauen und in einer moderaten Zeit herausfinden können was er macht. Magische Nummern: Benutze sie nicht! Benutze benannte Konstanten für alle literalen Werte mit Ausnahme von eindeutigen, speziellen Fällen. Grundsätzlich ist es in Ordnung mit einem Literal von 0 zu prüfen, ob ein Array 0 Elemente hat. Es ist nicht in Ordnung irgendeine spezielle Bedeutung einer Nummer zu zuordnen und diese irgendwo als Literal zu nutzen. Dieses verletzt die Lesbarkeit und die Haltbarkeit des Codes. In dieser Richtlinie ist enthalten, dass wir die Konstanten TRUE und FALSE anstatt der Literale 1 und 0 nutzen, obwohl sie die gleichen Werte haben. Das Benutzen dieser benannten Konstanten macht die angewandte Logik klarer. Vereinfachte Operatoren: Die einzigen vereinfachten Operatoren, die der Lesbarkeit schaden sind die vereinfachten Erhöhungs- (i++) und Verminderungs- (i--) Operatoren. Diese Operatoren sollten nicht als ein Teil eines Ausdrucks verwendet werden. Sie können jedoch in einer eigenen Zeile verwendet werden. Die Nutzung in Ausdrücken sind die Kopfschmerzen bei der Fehlersuche nicht wert. Beispiele: /* FALSCH */ $array[++$i] = $j; $array[$i++] = $k; /* RICHTIG */ $i++; $array[$i] = $j; $array[$i] = $k; $i++; Inline conditionals: Inline conditionals sollten nur genutzt werden um sehr einfache Dinge zu machen. Vorzugsweise werden sie nur genutzt um Zuweisungen zu machen und nicht für Funktions-Aufrufe oder überhaupt für irgendetwas kompliziertes. Wenn sie falsch angewandt werden können sie der Lesbarkeit schaden. Gewöhn dich gar nicht erst daran sie zu benutzen. Beispiele: * Schlechter Einsatz */ (($i < $size) && ($j > $size)) ? do_stuff($foo) : do_stuff($bar); /* Einsatz in Ordnung */ $min = ($i < $j) ? $i : $j; Verwende keine nicht initialisierten Variablen. Für phpBB2 planen wir einen höheren Level des Laufzeit Fehler Reportings. Das heißt, dass die Verwendung von nicht initialisierten Variablen als Fehler angezeigt wird. Dies wird oft vorkommen, wenn geprüft wird, welche der HTML bildenden Variablen bereits durchlaufen wurde. Diese Fehler können durch die Verwendung der eingebetteten isset() Funktion bei der Prüfung ob eine Variable bereits gesetzt wurde vermieden werden. Beispiele: /* Herkömmlicher Weg */ if ($forum) ... /* Neuer Weg */ if (isset($forum)) ... Top