Joomla! Programmier/Coding Standards (in der Folge Code)

Gute Code-Standards sind in jedem Entwickler-Projekt wichtig, aber speziell wenn mehrere Entwickler an dem selben Projekt arbeiten. Code-Standards zu haben hilft dabei die hohe Codequalität zu sichern, die Fehler zu verringern und ihn leichter zu pflegen.

Code Standards

Einrückungen und Zeilenlänge
Benutzen Sie eine Einrückung von 4 Leerzeichen. Wenn Sie Emacs (spezieller Texteditor) zum Editieren von Joomla!-Code benutzt, sollte der „Einrücken-Vorspring-Modus“ auf null gesetzt werden. Es wird empfohlen die Zeilen nach 75-85 Zeichen umzubrechen. Es gibt keine Standardregel für den Umbruch, nutzen sie im Zweifel ihr Urteilsvermögen.

Kontroll-Strukturen
Dies betrifft if, for, while, switch usw. Hier ist ein If-Anweisungs-Beispiel, weil es das komplizierteste der Genannten ist.

Beispielcode:

Steueranweisungen sollten eine Leerzeichen zwischen demSteuerschlüsselwort und den öffnenden Klammer haben, um sie von den Funktionsaufrufen zu unterscheiden.

Es wird stark empfohlen geschweifte Klammern {}sogar dort zu benutzen, wo die Nutzung technisch frei wählbar ist. Diese zu haben erhöht die Lesbarkeit und vermindert die Möglichkeit von logischen Störungen, die sich ergeben, wenn neue Zeilen hinzugefügt werden.

Für Switch-Anweisungen:
Beispielcode:

Funktionsaufrufe

Funktionen sollten ohne Leerzeichen zwischen em Funktionsnamen und den öffnenden Klammern, einem Leerzeichen vordem ersten Parameter, Leerzeichen zwischen Kommata und den Parametern, und einem Leerzeichen vor dem letzten Parameter sowie keinem eerzeichen zu den schliessenden Klammern und den Semikoli aufgerufenwerden.

Beispielcode:

Wie oben angezeigt, sollte ein Leerzeichen auf jeder Seite des Gleichheitszeichen sein, um einer Variablen den Rückholwert einer Funktion zuzuweisen. Im Falle eines Blockes in Verbindung stehender Anweisungen, können mehr Leerzeichen eingesetzt werden, um die Lesbarkeit zu fördern:

Beispielcode:



Funktionsdefinitionen folgen der einzig wahren Klammer-Übereinkunft

Beispielcode:

Argumente mit Standardwerten kommen an das Ende der Argumente-Liste. Versuchen Sie immer einen sinnvollen Wert zurück zu geben, falls einer angebracht ist. Hier ein etwas längeres Beispiel:

Beispielcode:

Kommentare
Eingebettete Dokumentation für Klassen (classes) sollten der PHPDoc-Übereinkunft, ähnlich der Javadoc, folgen. Mehr Informationen über PHPDoc können hier http://www.phpdoc.org/ gefunden werden.

Sehen Sie auch: Adding PHPDocumentor comments

Nicht-Dokumentations Kommentare werden stark empfohlen. Eine Daumenregel ist: wenn ein Abschnitt des Codes von Ihnen betrachtet wird und Sie denken „Boah, ich will gar nicht versuchen, das zu beschreiben“, muss es kommentiert werden, bevor vergessen wird wie es funktioniert.
Kommentare im C-Stil (/**/) und Standard C++ Kommentare (//) sind beide geeignet. Die Benutzung von Perl/shell Kommentaren (#) werden nicht empfohlen.

Code einbinden
Wo immer eine Klassen-Datei (Class-file) ohne Bedingungen benutzt werden muss, benutzen Sie „require_once()“. Überall wo eine bedingte Klassen-Datei (Class-file) benutzt wird verwenden Sie „include_once()“. Beide von diesen stellen sicher, dass diese Klassen-Dateien nur einmal benutzt werden. Sie teilen sich eine Dateiliste, Sie müssen sich nicht um das Mischen verschiedener Stile sorgen. Eine Datei, die mit „require_once()“ eingebunden wurde, wird nicht nochmal durch „include_once()“ eingebunden.
Hinweis: „include_once()“ und „require_once()“ sind Anweisungungen, keine Funktionen. Es werden keine Klammern um den Dateinamen benutzt.
PHP Code Tags
Alle Quellprogramm-Dateien innerhalb der PEAR-Distribution sollten folgenden Kommentarblock als Kopf enthalten:

Beispielcode:


Es gibt keine feste Regel, wann ein neuer Mitwirkender am Code für eine gegebene Quelldatei der Liste der Autoren hinzugefügt werden soll. Generell sollten die Änderungen in die Kategorie „erheblich“ fallen, das bedeutet irgendwo zwischen 10% und 20% an Änderungen am Code. Ausnahmen konnten für das Neuschreiben von Funktionen oder einer der neuen Logikfunktion gebildet werden. Einfache Codeänderungen oder Fehlerbehebungen (Bugfixes) rechtfertigen nicht das Hinzufügen eines neuen Individuums auf die Autorenliste.
Dateien, die nicht den Joomla!-Kern betreffen, sollten einen ähnlichen Block haben, in dem das Copyright, die Lizenz und der/die Autor(en) angegeben werden. Alle Dateien sollten die Codezeilen-Kommentare beinhalten, um die Übereinstimmungen zu fördern.

Beispiel-Urls

Benutzen Sie „example.com“, „example.org“ und „example.net“ für Beispiel-URLs und Emailadressen, gemäss dem technischen Standarddokument RFC2606.
Namensübereinkommen
Klassen (Classes)
Klassen sollte ein beschreibender Name gegeben werden. Vermeiden Sie es Abkürzungen zu verwenden. Klassennamen sollten immer mit einem Grossbuchstaben beginnen.

Funktionen und Methoden sollten den „hüpfenden-Grossbuchstaben-Stil“ (bumpy case, studly caps, camel caps) verwenden. Fnktionen sollten zusätzlich den Paketnamen als Präfix haben, um Namenskonflikte zwischen den einzelnen Paketen zu vermeiden. Der Anfangsbuchstabe des Namens (nach dem Präfix) wird klein und jeder Buchstabe der ein neues Wort beginnt wird gross geschrieben. Einige Beispiele:

Beispielcode:

Private Klassen Mitglieder (class-members) (bedeutet Klassen-Mitglieder, die nur innerhalb einer Klasse verwendet werden sollen, in der sie auch erklärt werden. PHP unterstützt noch nicht zutreffend durchsetzbare eigene Namensräume)wird ein Unterstrich vorangesetzt.

Beispielcode:

Konstanten
sollten immer komplett in Grossbuchstaben mit Unterstrichen zum nächsten Wort sein, Präfixe der Namen von Konstanten mit dem gross geschriebenen Namen der Klasse (Class)/Paketes, in welchem sie benutzt werden. Als Beispiel: Die Konstanten die von DB-Paketen benutzt werden beginnen alle mit DB_.

Globale Variablen
Wenn Ihr Paketglobale Variablen definieren muss, sollte ihr Name mit einem einzelnen Unterstrich beginnen, gefolgt vom Paketnamen und einem weiteren Unterstrich. Das Pear-Paket benutzt zum Beispiel die folgende globale Variable, genannt „$_PEAR_destructor_object_list“.

 

Kommentar schreiben