Programmierung: Guter Stil

Ein paar grundsätzliche Bemerkungen zum Programmieren, die durchaus als Empfehlungen gewertet werden dürfen.

Code sollte möglichst so geschrieben und formatiert sein, dass er verständlich, nachvollziehbar und gut lesbar ist. Bedenke: Es ist immer möglich, dass ein Außenstehender deinen Code verstehen muss, bevor er ihn ändern kann (aus welchen Gründen auch immer; Hilfe, Verbesserung, Individualisierung).

Jeder Narr kann Code schreiben, den ein Computer verstehen kann.
Gute Programmierer schreiben Code, den Menschen verstehen können.

Martin Fowler

Seit CMSimple_XH 1.6 wurden die Pear Programmierung Standards für das Kernsystem angenommen. Schreiber von Erweiterungen können in Erwägung ziehen, diese Coding Standards ebenfalls anzunehmen, aber natürlich ist das nicht verpflichtend.

Tipps

1. Schreibe immer <?php … ?> oder <?= … ?> – niemals die Kurzfassung <? … ?>, denn diese könnte PHP beim Parsen falsch interpretieren.
2. Wähle verständliche Namen für Funktionen und Variablen und vermeide es – soweit möglich – neue globale Variablen einzuführen. Stelle deinen Funktionen z.B. den Namen des Plugins voran – so ist immer klar, was wozu gehört und mögliche Konflikte mit anderen Funktionen werden vermieden.
3. Rücke deinen Code mit 4 Leerzeichen auf eine logische Weise ein.
4. Verwende geschweifte Klammern – selbst dann, wenn es gar nicht erforderlich wäre. Beispiel:
   

   // schlecht (das betrifft ebenfalls Punkt #2):
   if ($t == '')e('undefined', 'file', $fl);
   
   // besser:
   if ($temp == '') {
       error_message('undefined', 'file', $file);
   }​
   

5. Verwende einfache Anführungszeichen, zumindest für den Fall, dass in der Zeichenkette nichts zu evaluieren ist. Beispiel:
   

   // schlecht:
   echo "<a href=\"https://www.cmsimple-xh.org\" title=\"CMSimple_XH\">CMSimple_XH</a>";
   
   // besser:
   echo '<a href="https://www.cmsimple-xh.org" title="CMSimple_XH">CMSimple_XH</a>';​

6. Trenne Parameter und Operatoren mit Leerzeichen. Beispiel:
   

   // schlecht:
   function some_function($foo,$bar){
       if($foo==bar){
            return $foo+$bar;
       }
   }
   
   // besser:
   function some_function($foo, $bar) {
       if($foo == bar) {
           return $foo + $bar;
       }
   }​

7. Im Falle vieler Parameter oder Bedingungsklauseln, verwende Zeilenumbrüche und Einrückungen. Beispiel:

   // schlecht:
   if(isset($foo) && $foo > 1 && $foo < 45 && $bar == true){
       //...
   }
   
   // besser:
   if(isset($foo)
       && $foo > 1
       && $foo < 45
       && $bar == true
   ) {
       //...
   }

8. Verschachtele nicht zu tief, und schreibe kurze Code-Zeilen (max. 80 Zeichen). Beispiel:
   

   // schlecht:
   $foo = explode('§', preg_replace("/(<h[1-".$cf['menu']['levels']."][^>]*>)/i", "§\\1", str_replace('§', '&#167;', rf($pth['file']['content']))));
    
   // besser:
   $foo = rf($pth['file']['content']);
   $foo = str_replace('§', '&#167;' $foo);
   $foo = preg_replace('/(<h[1-'
        . $cf['menu']['levels']
        . '][^>]*>)/i', '§\\1', $foo);
   $foo = explode('§', $foo);​
   ...

   Bei kurzen Zeilen: Platziere die Verkettungs-Punkte in mehreren Zeilen genau unter das =. Beispiel:

   // schlecht:
   $foo = $foo1.$foo2.$foo3.(my_super_cool_calculation).etc;
    
   // besser:
   $foo = $foo1
        . $foo2
        . $foo3
        . (my_super_cool_calculation)
        . etc;

9. Funktionsnamen sind besser zu lang als zu kurz. Eine beschreibende Phrase als Funktionsname erleichtert die Verständlichkeit des Codes. Beginne mit einem Kleinbuchstaben und trenne Wörter durch camelCase oder Unterstriche.

   // schlecht
   function meineeigenefunktion() {
       ...
   }
   // besser - camelCase
   function meineEigeneFunktion() {
       ...
   }
   // noch besser - Pluginname + Unterstrich + camelCase kombiniert
   function meinPlugin_meineEigeneFunktion() {
       ...
   }​

10. Klassendefinitionen sollten mit einem Großbuchstaben beginnen und einen Zeilenumbruch vor der öffnenden Klammer haben.

    class Toy
    {
        //...
    }

11. Rücke Zuordnungen in Arrays ein.

    // schlecht:
    array('drink' => 'coffee', 'do_not_watch'=>'tv','eat'=>'bread');
    
    // besser:
    array(
        'drink'        => 'coffee',
        'do_not_watch' => 'tv',
        'eat'          => 'bread',
    );

12. Das Wichtigste zuletzt: Kommentiere ausführlich, wo und wann immer es angebracht ist!
    Du musst nicht befürchten, dass irgendetwas wegen zu vieler langsamer läuft – also die Performance leidet. Die Kommentare werden von PHP nicht beachtet und auch nicht übertragen! HTML- oder JavaScript-Kommentare werden zwar übertragen, der Zugewinn bei der Übersichtlichkeit überwiegt jedoch.