Coding Standards Brandbox

Transkript

1 Coding Standards Brandbox Einrückungen und Zeilenlänge...2 Kontrollstrukturen...2 Klassen...3 Funktionen...3 Deklaration... 3 Aufruf... 4 Kommentare...4 PHP-Code-Tags...4 Konventionen, Style, Sprache...5 PHP:... 5 Javascript:... 5 CSS:... 5 Funktionen und Methoden... 5 Konstanten... 5 Variablen... 5 Zuweisungen innerhalb Methoden...6 Dateiformate...6 Anführungszeichen...6 E_STRICT-kompatibler Code...6 Brandbox...7 Überschreiben und Überladen von Methoden... 7 Bezeichnung von Methoden... 7 Models... 7 Klassen Accessors und Comparators... 8 Accessors... 8 Comparators... 8 Namen von Extensions... 8 Identifier... 8 Die Brandbox Coding Standards gelten für Quellcode der in Form von Extensions, Models Modulen, Themes oder im Framework geschrieben wird. Ihr Ziel ist es, den Quellcode konsistent zu halten und somit allen Beteiligten zu erleichtern den Quellcode zu lesen und zu betreuen. Dirk Gnauck / / Seite 1 von 8

2 Einrückungen und Zeilenlänge Benutzen Sie Einrückungen mit 2 Leerzeichen, keine Tabulatoren. Damit helfen Sie, Probleme zu vermeiden, die mit Diffs, Patches und anderen CVS-Funktionen entstehen. Wir empfehlen eine Zeile nach ca Zeichen zu umbrechen. Die meisten Entwicklungsumgebungen ermöglichen die Darstellung einer Linie nach einer bestimmten Anzahl an Zeichen. Kontrollstrukturen Darunter fallen if, for, while, switch usw. Hier ist ein Beispiel für eine if-konstruktion, da sie eine der komplizierten ist: if(condition1 condition2): // action1; elseif(condition3 && condition4): // action2; else: // default-action; endif; switch(condition): case 1: // action1; break; default: // default-action; break; endswitch; Kontroll-Ausdrücke sollten kein Leerzeichen zwischen den Schlüsselwörtern und der öffnenden Klammer haben, um den Quellcode kompakter zu gestalten. Bitte verwenden Sie die alternative Syntax. Sie sollten unbedingt Doppelpunkte verwenden, auch wenn sie technisch nur optional sind. Damit verbessern Sie die Lesbarkeit und vermeiden logische Fehler, wenn neue Zeilen hinzugefügt werden. Dirk Gnauck / / Seite 2 von 8

3 Klassen Die öffnende Klammer einer Klassen-Deklaration beginnt nicht auf einer neuen Zeile: class foobar { //... ihr Code Funktionen Deklaration Funktionsdeklarationen folgen dem "1TBStyle" (One True Brace Style): function foobar($arg1, $arg2 = '') { if(condition): // statement; endif; return $val; Argumente mit Standardwerten werden am Ende der Parameterliste platziert. Eine Methode liefert immer einen eindeutig typisierten Wert zurück. Hier ein Beispiel: function foobar($arg1, $arg2= false) { return true; Dirk Gnauck / / Seite 3 von 8

4 Aufruf Funktionen sollten ohne Leerzeichen zwischen dem Funktionsnamen, der öffnenden Klammer und dem ersten Parameter aufgerufen werden. Leerzeichen sollten gesetzt werden zwischen Komma und jedem Parameter. Zwischen dem letzten Parameter, der schließenden Klammer und Semikolon sollten keine Leerzeichen gesetzt werden. Ein Beispiel: $var = foo($bar1, $bar2, $bar3); Wie oben gezeigt, sollte ein Leerzeichen vor und hinter das Gleichheitszeichen gesetzt werden, wenn der Rückgabewert der Funktion einer Variable zugewiesen wird. Kommentare PHPDoc-Kommentare erlauben die Dokumentation von Klassen, Methoden und Variablen und stellen eine API-Dokumentation zur Verfügung. Die Signatur sowie der Rückgabewert einer Methode müssen korrekt und vollständig beschrieben werden. Der PHPDoc-Abschnitt enthält Informationen zu Eingabeparameter (@param), Rückgabewerte (@return) und Autor(ren) der Methode (@author). /** Vorname Nachname, Vorname2 Nachname2 string $param1 boolean $param2 boolean */ PHP-Code-Tags Benutzen Sie immer um Ihren PHP-Code zu markieren, niemals die Kurzform <?. Die erste Variante funktioniert unabhängig vom Betriebssystem und der PHP-Konfiguration. Der PHP-Code muss immer geschlossen werden. Dirk Gnauck / / Seite 4 von 8

5 Konventionen, Style, Sprache Grundsätzlich werden alle Klassen-, Methoden- und Variablennamen sowie Konstanten in Englisch geschrieben. Es gilt beschreibende Bezeichnungen zu verwenden. Es werden auch keine Abkürzungen verwendet. Die Notation aller Sprachelemente in allen Sprache (PHP, Javascript und CSS) ist lowercamelcase. PHP: class myclass { const mystaticnote = "..."; function myphp() { Javascript: function myjavascript() { CSS:.myClass { <div id="yourid" class="myclass"></div> Funktionen und Methoden Die Methodennamen sollten bereits eine kurze Info über Sinn und Aufgabe der Methode enthalten. Dies kann auch dazu führen, dass die Methodennamen lang werden. getnewssortedbynewsdate() Konstanten Konstanten folgen den gleichen Konventionen wie die anderen Sprachelemente. Beispiele: self::myconst, self::tableid Variablen Auch wenn in PHP die Variablen nicht mit einem speziellen Datentyp initialisiert werden müssen, sollte darauf geachtet werden, dass der Datentyp zur Laufzeit nicht mehr geändert wird. D.h. eine Variable die einen Integer-Wert enthält sollte nicht mit einem String-Wert gefüllt werden. Die Variablen, Eingabe- und Ausgabeparameter sind ausnahmslos zu casten, damit der Datentyp eindeutig ist. Während der Verarbeitung darf der Dateityp sich nicht ändern. Dirk Gnauck / / Seite 5 von 8

6 Zuweisungen innerhalb Methoden Ist eine Variable einmal zugewiesen, sollte eine weitere Zuweisung der Variable innerhalb einer Funktion vermieden werden. $x = $y + $z; $a = $x*2; Dateiformate PHP-, JavaScript-, CSS-Dateien und TPL-Dateien müssen in UTF-8 (ohne BOM) encodiert werden. Anführungszeichen Es werden einfache Anführungszeichen im Code verwendet. E_STRICT-kompatibler Code Code sollte prinzipiell E_STRICT-kompatibel sein. Das heißt, er darf keine Fehler oder Warnungen erzeugen, wenn das Fehler-Reporting von PHP auf E_STRICT eingestellt ist. Dirk Gnauck / / Seite 6 von 8

7 Brandbox Überschreiben und Überladen von Methoden Da ab Brandbox 3 fast alle Klassen von einer übergeordneten Model-/Engine-Klasse abgeleitet werden, bietet sich das Überschreiben und Überladen von Methoden an. Wenn möglich sollte allerdings die Kernfunktion bei Methoden weiter erhalten bleiben. public function getvalue() { $parent = parent::getvalue(); return $parent; Bestehende Methoden sollen nicht überschrieben werden. Andernfalls ist die Update-Sicherheit nicht mehr gewährleistet ist. Der Konstruktor wird nicht überschrieben. Bezeichnung von Methoden Methoden sollen grundsätzlich mit einem der folgenden führenden Wörter notiert werden: is, has, get, set, exec, view Optional kann entschieden werden ob exec entfällt und stattdessen ein Verb als Prefix verwendet wird. Das gilt jedoch nur für Methoden die andernfalls mit exec notiert werden würden. Models Models sind nach dem Singleton-Pattern angelegt, d.h. mit Hilfe der get()-methode wird immer die aktuelle Instanz geladen. Bei der Entwicklung von eigenen Models muss mindestens die Klasse \BB\model abgeleitet werden und die Variable protected static $instance = null; definiert sein. Bei der Definition neuer Models muss darauf geachtet werden, dass diese nicht vorhandene Brandbox-Models beeinflussen. Models werden immer dann aufgerufen, wenn Sie in einer Methode verwendet werden. Eine Initialisierung an einer zentralen Stelle in der Klasse ist nicht notwendig. Dirk Gnauck / / Seite 7 von 8

8 Klassen Accessors und Comparators Models sollen so gut wie möglichst voneinander getrennt werden. Es ist sinnvoll in der Extension einen Autoloader zu schreiben mit die Differenzierung zwischen Accessors, Comparators, Helper, Exception, Preset, usw. möglich wird. Accessors Accessors sind data access objects. Sie sollen die Daten aus einer Tabelle lesen und schreiben. Im Accessor wird für jedes Feld einer Tabelle eine set- und und eine get-methode geschrieben. Der Name dieser Klassen richtet sich nach der Tabelle. Comparators Comparators sind models die Verknüpfungen zwischen zwei Tabellen lesen und schreiben. Sollte es notwendig sein mehrere Tabellen zu behandeln müssen jeweils eigene comparators geschrieben werden. Der Name dieser Klassen richtet sich nach den beiden Tabellen die betroffen sind: parenttablechildtable. Namen von Extensions Extensions unterliegen ebenfalls dem lowercamelcase-style mit englischer Bezeichnung. Identifier Identifier werden in folgender Form auf Englisch notiert: Tabellengruppe:Tabelle:Feld Dirk Gnauck / / Seite 8 von 8