|
ProgrammierRichtlinien
Richtlinien zur Programmierung, Coding Style Guide.
AllgemeinDie Namensgebung und die Kommentare werden in Englisch verfasst. EinrückungWir 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>';KontrollstrukturenMit Kontrollstrukturen sind folgende Elemente gemeint:
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 einzeilligHier noch ein Beispiel für eine switch/case-Anweisung: switch(bedingung)
{
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}FunktionsaufrufeEin 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 FunktionenBeim 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;
}KommentareDamit 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-TagsMan 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 DateienJede 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 NamenskonventionenKlassenKlassen sollen selbstsprechende Namen erhalten. Kryptische Abkürzungen sollte man wenn möglich vermeiden. Klassen sollten immer mit einem Großbuchstaben beginnen. FunktionenFunktionsnamen 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(); VariablenVariablen 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 KonstantenBei Konstanten werden alle Buchstaben groß geschrieben und die einzelnen Worte innerhalb des Namens durch Unterstriche getrennt. Beispiel: TBL_ORGANIZATIONS DateiformateUm die Entwicklung auf verschiedenen Systemen zu gewährleisten muss ein einheitliches Format genutzt werden:
DateinamenHier ist die übliche Namensgebung des Zend Frameworks zu verwenden. Gebrauch von AnführungszeichenStrings 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 $string3Argumente 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" '; |