My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
ProgrammierRichtlinien  
Richtlinien zur Programmierung, Coding Style Guide.
Updated Nov 12, 2012 by edona....@googlemail.com

Allgemein

Die Namensgebung und die Kommentare werden in Englisch verfasst.

Einrückung

Wir haben uns für Einrückungen von einem Tab pro Ebene entschieden. Das heißt, in der Entwicklungsumgebung muss eingestellt sein, dass Einrückungen mit einem Tab gemacht werden, diese sollen beim speichern nicht durch Leerzeichen ersetzt werden. So kann sich jeder die gewünschte Einrückung selbst einstellen, in dem er in seiner Entwicklungsumgebung einstellt wievielen Leerzeichen ein Tab entsprechen soll. Die Einrückung gilt dann sowohl für PHP, JavaScript und HTML-Code.

echo '
<table>
    <tr>
        <td>Nur ein Test</td>
    </tr>
</table>';

Kontrollstrukturen

Mit Kontrollstrukturen sind folgende Elemente gemeint:

  • if
  • for
  • while
  • switch
Hierbei sollte darauf geachtet werden, dass die geschweiften Klammern immer auf der Höhe der zugehörigen Kontrollstruktur in einer separaten Zeile stehen! Hier ein Beispiel für eine verschachtelte if-Anweisung:

if((bedingung1) && (bedingung2))
{
    action1;
    if(bedingung3) //hier werden keine {} gebraucht, da einzeillig
        action2;
}
elseif((bedingung4) || (bedingung5))
{
    action3;
    action4;
}
else
    defaultaction; //auch hier werden keine {} gebraucht, da einzeillig

Hier noch ein Beispiel für eine switch/case-Anweisung:

switch(bedingung)
{
    case 1:
        action1;
        break;
 
    case 2:
        action2;
        break;
 
    default:
        defaultaction;
        break;
}

Funktionsaufrufe

Ein Funktionsaufruf geschieht immer ohne Leerzeichen zwischen dem Funktionsnamen, der öffnenden Klammer und dem ersten Übergabeparameter. Die einzelnen Parameter werden mit Komma und Leerzeichen voneinander getrennt. Hinter dem letzten Parameter wird ebenfalls kein Leerzeichen mehr eingesetzt. Anbei wieder ein Beispiel:

$var = funktion($para1, $para2, $para3);

Wie oben gezeigt steht auf der linken und rechten Seite des Gleichheitszeichens jeweils ein Leerzeichen. Wenn mehrere Funktionsaufrufe und damit Variablenzuweisungen im Block untereinander stehen, kann, um die Lesbarkeit des Codes zu gewährleisten, davon abgewichen werden:

$kurz        = foo($para1);
$langerName = foo($para2);

Definieren von Funktionen

Beim Definieren von Funktionen wandern die Argumente mit Default-Werten ans Ende der Deklaration. Funktionsnamen, Argumente und Rückgabewerte sollten selbsterklärend sein. Hier ein Beispiel:

function addition($wert1, $wert2, $wert3 = 0)
{
    $ergebnis = $wert1 + $wert2 + $wert3;
 
    return $ergebnis;
}

Kommentare

Damit auch andere die eventuell vorhanden Bugs in eurem Code fixen können, muss dieser nicht nur übersichtlich, sondern auch verständlich sein. Daher ist der ein oder andere Kommentar unumgänglich. Hier ist der richtige Mittelweg zu wählen. Zu viel Kommentar verschränkt den Blick auf das wesentliche (den Code), zu wenig Kommentar lässt ihn undurchdringbar erscheinen… Kommentare direkt im Sourcecode (keine Funktions- und Methodenbeschreibung) müssen eingerückt werden. So dass sie auf derselben Ebene wie das zu kommentierende Konstrukt stehen. Ein- bis zweizeilige Kommentare werden wie folgt dargestellt:

//Dies ist die erste Zeile ueberfluessiger Kommentar
//Dies ist die weite Zeile ueberfluessiger Kommentar

Wie oben zu sehen ist, sollte auch in Kommentaren von Umlauten abgesehen werden. Erstreckt sich ein Kommentar über mehr als 2 Zeilen sollten Block-Kommentare eingesetzt werden:

/*
*
* Dieser Kommentar koennte jetzt noch ewig weitergehen...
* Dieser Kommentar koennte jetzt noch ewig weitergehen...
* Dieser Kommentar koennte jetzt noch ewig weitergehen...
* Dieser Kommentar koennte jetzt noch ewig weitergehen...
* Aber so viel Spass habe ich auch nicht beim kommentieren!
*
*/

Wichtig bei Blockkommentaren sind die "*" am Anfang der Zeilen. Diese sind nicht notwendig, erleichtern aber den Überblick erheblich und sollten deshalb gesetzt werden.

Klassen, Methoden, globale Variablen u.ä. sollten entsprechend der Richtlinien des phpDocumentors dokumentiert werden:

/**
 * Hier sollte eine passende Beschreibung
 * der Klasse stehen.
 */
class FooClass
{
  ...
}

Mehr Informationen sind unter http://www.phpdoc.org zu finden.

PHP-Code-Tags

Man muss um den PHP-Code herum immer die Tags <?php und ?> setzen und nicht die Kurzform <? ?>. Dies ist die einzige Möglichkeit zu gewährleisten, dass der Code auf allen Plattformen auch als PHP-Code interpretiert wird.

Header von Dateien

Jede Datei sollte am Anfang der Datei einen DocBlock enthalten. Dieser muss eine kurze Erklärung des PHP-Scripts enthalten. Außerdem sind hier fein säuberlich alle möglichen Übergabewerte des Scripts aufgelistet… Hier ein Beispiel aus dem Internet:

/******************************************************************************
 * Verschiedene Funktionen fuer Termine
 *
 * Copyright    : …..
 * Homepage     : …..
 * Module-Owner : Vor- und Nachname des Entwicklers
 * License      : …………..
 * Uebergaben:
 *
 *    
*****************************************************************************/

TODO: Beispiel durch phpDocumentator Beispiel ersetzen

Namenskonventionen

Klassen

Klassen sollen selbstsprechende Namen erhalten. Kryptische Abkürzungen sollte man wenn möglich vermeiden. Klassen sollten immer mit einem Großbuchstaben beginnen.

Funktionen

Funktionsnamen sollten im camelStyle (vielen auch als camelCaps oder laOlaStyle bekannt) geschrieben werden. Dies soll heißen, das der erste Buchstabe klein geschrieben ist und der erste Buchstabe des nächsten Wortes groß. Beispiel: getSystemData();

Variablen

Variablen sollten ähnlich den Funktionsnamen im camelStyle (vielen auch als camelCaps oder laOlaStyle bekannt) geschrieben werden. Globale Variablen, die systemweit gelten erhalten ein g als Präfix, Übergabevariablen an ein Script erhalten ein get bzw. post als Präfix, damit immer direkt klar ist, dass der Inhalt der Varialben manipuliert sein kann. Beispiel:

numberRows  // Varialbenbezeichnung
gCurrentUser  // globale Varialbe
getUserId  // Übergabevariable an ein Script

TODO: Beispiel durch phpDocumentator Beispiel ersetzen

Konstanten

Bei Konstanten werden alle Buchstaben groß geschrieben und die einzelnen Worte innerhalb des Namens durch Unterstriche getrennt. Beispiel:

TBL_ORGANIZATIONS

Dateiformate

Um die Entwicklung auf verschiedenen Systemen zu gewährleisten muss ein einheitliches Format genutzt werden:

  • Zeichensatz UTF-8
  • Zeilenumbruch Windows (CRLF)
Bei UTF-8 ist noch zu beachten, dass der Editor das Byte-Order-Flag (BOM) nicht setzen darf. Dieses Flag dient eigentlich zur genauen Identifizierung des verwendeten UTF Kodierung (UTF-8, UTF-16 oder UTF-32). Verwendet man dieses aber in PHP, so wird es einfach am Scriptanfang im Browser ausgegeben und führt dann auch meistens zu einer Fehlermeldung im Script.

Dateinamen

Hier ist die übliche Namensgebung des Zend Frameworks zu verwenden.

Gebrauch von Anführungszeichen

Strings werden, soweit sinnvoll in einfache Anführungszeichen gesetzt. Das hat den Grund, dass PHP Strings in doppelten Anführungszeichen automatisch parst, solche in einfachen Anführungszeichen werden aber direkt übernommen. Werden also viele Variablen im String genutzt, dann sind durchaus auch doppelte Anführungszeichen sinnvoll. Beispiel:

$array['element'] = $object->getValue('id');
$string = 'example';
$string2 = 'testing';
$string3 = "$string2 $string";  //Ergebnis identisch zu $string4
$string4 = $string2.' '.$string;//Ergebnis identisch zu $string3

Argumente innerhalb von Strings werden in doppelte Anführungszeichen gesetzt. Beispiel:

echo '<img src="bild1.jpg" alt="Bild" />';
$sql = 'SELECT * FROM '. TBL_TEXT. ' WHERE txt_value = "beispiel" ';
Powered by Google Project Hosting