Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
de:entwickler:programmierrichtlinien [2009/01/12 14:57] – jochende:entwickler:programmierrichtlinien [2024/12/02 18:21] (current) – [Kommentare] greno
Line 50: Line 50:
  
   * Wer möchte kann 1 Leerzeichen zwischen ControlKeyword (if) und der Bedingung machen, um sie von Methodenaufrufen abzugrenzen. Dies ist aber jedem selbst überlassen.   * Wer möchte kann 1 Leerzeichen zwischen ControlKeyword (if) und der Bedingung machen, um sie von Methodenaufrufen abzugrenzen. Dies ist aber jedem selbst überlassen.
-  * auch wenn nur eine Action definiert ist immer geschweifte Klammern nutzen+  * auch wenn nur eine Aktion definiert ist immer geschweifte Klammern nutzen
  
 Hier noch ein Beispiel für eine switch/case-Anweisung:  Hier noch ein Beispiel für eine switch/case-Anweisung: 
Line 68: Line 68:
 }</code> }</code>
  
 +Verkürzte Schreibweisen, wie zum Beispiel die folgende If-Anweisung sollten aus Gründen der Übersichtlichkeit vermieden werden!
 +<code php>(bedingung) ? action1 : action2</code>
 ===== Funktionsaufrufe ===== ===== 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 von einander getrennt. Hinter dem letztem Parameter wird ebenfalls kein Leerzeichen mehr eingesetzt. Anbei wieder ein Beispiel: +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 letztem Parameter wird ebenfalls kein Leerzeichen mehr eingesetzt. Anbei wieder ein Beispiel: 
 <code php>$var = funktion($para1, $para2, $para3);</code> <code php>$var = funktion($para1, $para2, $para3);</code>
 Wie oben gezeigt steht auf der linken und rechten Seite des Gleichheitszeichen 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:  Wie oben gezeigt steht auf der linken und rechten Seite des Gleichheitszeichen 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: 
Line 85: Line 87:
  
 ===== Kommentare ===== ===== 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...+Damit auch andere die eventuell vorhanden Bugs in deinem Code fixen können, muss dieser nicht nur übersichtlich, sondern auch verständlich sein. Daher ist der eine 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 müssen ebenfalls eingerückt werden. So dass sie auf der selben Ebene wie das zu kommentierende Konstrukt stehen. Ein- bis zweizeilige Kommentare werden wie folgt dargestellt:  +Kommentare sollten in der Regel in englisch erfasst werden, so dass der Sourcecode auch von nicht deutschsprachigen Entwicklern gelesen werden kann. Bei der Dokumentation von Klassen, Methoden und Funktionen verwenden wir zur Unterstützung Doxygen. Damit kann eine übersichtliche HTML-Hilfe erstellt werden. Allerdings müssen dazu ein paar Tags innerhalb des Kommentars gesetzt werden. Eine [[de:entwickler:sourcecode-dokumentation|Beschreibung zur Dokumentation mit Doxygen]] ist aber vorhanden. 
-<code php>//Dies ist die erste Zeile ueberfluessiger Kommentar + 
-//Dies ist die weite Zeile ueberfluessiger Kommentar</code>+Kommentare direkt im Sourcecode (keine Funktions- und Methodenbeschreibung) müssen eingerückt werden. So dass sie auf der selben Ebene wie das zu kommentierende Konstrukt stehen. Ein- bis zweizeilige Kommentare werden wie folgt dargestellt:  
 +<code php>// This is the first line of a short comment 
 +// This is the second line of a short comment</code>
 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:  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: 
-<code php>/* +<code php>/* This comment could be very long ... 
-* +* This comment could be very long ... 
-* Dieser Kommentar koennte jetzt noch ewig weitergehen... +* This comment could be very long ... 
-* Dieser Kommentar koennte jetzt noch ewig weitergehen... +* This comment could be very very very long ...  */</code>
-* Dieser Kommentar koennte jetzt noch ewig weitergehen... +
-* Dieser Kommentar koennte jetzt noch ewig weitergehen... +
-* Aber soviel Spass habe ich auch nicht beim kommentieren! +
-* +
-*/</code>+
 Wichtig bei Blockkommentaren sind die * am Anfang der Zeilen. Diese sind nicht notwendig, erleichtern aber den Überblick erheblich und sollten deshalb gesetzt werden. Wichtig bei Blockkommentaren sind die * am Anfang der Zeilen. Diese sind nicht notwendig, erleichtern aber den Überblick erheblich und sollten deshalb gesetzt werden.
  
Line 135: Line 134:
  
 **Funktionen**\\  **Funktionen**\\ 
-Funktionsnamen sollten im camelStyle (vielen auch als camelCaps oder laOlaStyle bekannt) geschrieben werden. Dies soll heißen, dass der erste Buchstabe klein geschrieben ist und der erste Buchstabe des nächsten Wortes groß. Beispiel:+Funktionsnamen sollten im camelStyle (vielen auch als [[http://de.wikipedia.org/wiki/CamelCaps|camelCaps]] oder laOlaStyle bekannt) geschrieben werden. Dies soll heißen, dass der erste Buchstabe klein geschrieben ist und der erste Buchstabe des nächsten Wortes groß.\\  
 +Beispiel:
  
 <code php>getSystemData();</code> <code php>getSystemData();</code>
 +
 +**Variablen**\\ 
 +Variablen sollten ähnlich den Funktionsnamen im camelStyle (vielen auch als [[http://de.wikipedia.org/wiki/CamelCaps|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 Variablen manipuliert sein kann.\\ 
 +Beispiel:
 +
 +<code php>numberRows  // Varialbenbezeichnung
 +gCurrentUser  // globale Variable
 +getUserId  // Übergabevariable an ein Script</code>
  
 **Konstanten**\\  **Konstanten**\\ 
-Bei Konstanten werden alle Buchstaben groß geschrieben und die einlenen Worte innerhalb de Namens durch Unterstriche getrennt. Beispiel:+Bei Konstanten werden alle Buchstaben groß geschrieben und die einzelnen Worte innerhalb de Namens durch Unterstriche getrennt.\\  
 +Beispiel:
  
 <code php>TBL_ORGANIZATIONS</code> <code php>TBL_ORGANIZATIONS</code>
Line 152: Line 161:
 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.  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 =====
 +  * Dateinamen der Scripte müssen immer klein geschrieben werden, da einige Server immer noch so konfiguriert sind, dass sie mit der Großschreibung nicht klar kommen.
 +  * Besteht ein Scriptname aus mehreren Wörtern, so sollten diese durch einen Unterstrich _ getrennt werden\\ Beispiel: **new_user_function.php**
 +  * Das Hauptscript eines Moduls sollte genauso heißen, wie der Modulordner\\ Beispiel: **adm_program/modules/announcements/announcements.php**
  
-===== Schreibweisen ===== +===== Gebrauch von Anführungszeichen =====
-=== Gebrauch von Anführungszeichen ===+
 Alle Strings werden in einfache Anführungszeichen gesetzt. Beispiel: Alle Strings werden in einfache Anführungszeichen gesetzt. Beispiel:
-<code php>echo 'Text';</code>+<code php>$array['element'] = $object->getValue('id'); 
 +$string = 'example';</code> 
 Argumente innerhalb von Strings werden in doppelte Anführungszeichen gesetzt. Beispiel: Argumente innerhalb von Strings werden in doppelte Anführungszeichen gesetzt. Beispiel:
-<code php>echo '<img src="bild1.jpg">';</code>+<code php>echo '<img src="bild1.jpg" alt="Bild" />'; 
 +$sql = 'SELECT * FROM '. TBL_TEXT. ' WHERE txt_value = "beispiel" ';</code> 
 + 
 +Innerhalb von Javascript sollten dagegen die doppelten Anführungszeichen genutzt werden, damit so wenig wie möglich Zeichen escaped werden müssen. Damit Javascriptcode einfacher zwischen den Scripten kopiert werden kann, sollten wir auch bei reinen Javascript-Dateien die doppelten Anführungszeichen nehmen. 
 +<code php> 
 +echo '<script type="text/javascript"><!-- 
 +               var string = "doppelte Anführungszeichen"; 
 +               var array["element"]; 
 +--></script>';</code> 
 + 
 +Ausnahmen zu diesen Regeln ist Javasciptcode direkt in HTML-Attributen. Dort müssen die einfachen Anführungszeichen (escaped) genommen werden, da ansonsten das Attribut beendet wird. 
 +<code php>echo '<a href="javascript: beispiel(\'uebergabe\');" target="_self">Html-Code</a>';</code> 
 + 
 +===== Vergleichsoperatoren ===== 
 +Beim Vergleich des Inhalts von Variablen sollten diese so gewählt werden, dass auch der Typ (integer/string) mit geprüft wird. Dies erreicht man, indem man gleich mit **===** oder ungleich mit **!==** angibt. 
 +<code php>if($a == $b)  // prüft nur ob der Inhalt gleich ist. "Test" == Test   > true 
 +if($a === $b) // prüft ob auch der Typ gleich ist. "Test" === Test   > false 
 +              //                                   "Test" === "Test" > true 
 + 
 +if($a != $b)  // prüft nur ob der Inhalt ungleich ist. "Test" != Test2   > true 
 +if($a !== $b) // prüft ob auch der Typ gleich ist. "Test" !== Test   > false 
 +              //                                   "Test2" !== "Test" > true 
 +</code>
  • de/entwickler/programmierrichtlinien.1231768676.txt.gz
  • Last modified: 2009/01/12 14:57
  • by jochen