CMSimple_XH (1.7.X) Dokumentation

PHP Code Konventionen

Die unter CMSimple_XH 1.6 genutzten PEAR Coding-Standards wurden bei CMSimple_XH 1.7 durch den PSR-2 Coding-Standards abgelöst, deren Einhaltung mit "phing sniff" überprüft werden kann.
CMSimple_XH 1.7 hat unter anderem auch einen allgemeinen Klassen-Autoloader bekommen. Um ihn zu verwenden, müssen die passend in Namensräumen definierten Klassen in den classes/ Ordner des Plugins gelegt werden. Verschachtelte Namensräume werden ebenfalls unterstützt. Es wird empfohlen, sich aus Gründen der Einfachheit und Effizienz auf das Klassen-Autoloading zu verlassen anstatt PHP-Dateien manuell zu require'n.

Autoren von Erweiterungen wird empfohlen diese Coding Standards ebenfalls anzunehmen, aber natürlich ist dis nicht verpflichtend.
Zumindest die folgenden zehn Vorschläge sollten aber bei der Programmierung von Plugins, Addons und Anpassungen in Erwägung gezogen werden, damit der Code auch von anderen Entwicklern (einfacher und schneller) verstanden werden kann:

1. Immer <?php … ?> und nie die Kürzel <? … ?> oder <?= … ?> verwenden, da diese nicht überall verfügbar sind.

2. Es sollten verständliche (selbst sprechende) Namen für Funktionen und Variablen verwendet werden und es sollten nach Möglichkeit neue globale Variablen vermieden werden. Um Namenskollisionen zu vermeiden, sollten Funktionsnamen und andere globale Bezeichnern z.B. der Pluginname vorangestellt werden (Namespaces sind erst seit PHP 5.3 möglich).

3. Code auf der gleichen logischen Ebene sollte immer mit 4 Leerzeichen bzw. mit 4 Zeichen langen Tabulatoren auf gleiche Höhe eingerückt werden.

4. Es wird die Verwendung von geschweiften Klammern empfohlen, auch wenn sie nicht (unbedingt) erforderlich sind. Beispiel:

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

5. Es sollten einfache Anführungszeichen benutzt werden, wenn in der Zeichenkette keine Interpolation erfolgen muss.

   // schlecht:
   echo "<a href=\http://www.cmsimple.org\" title=\"CMSimple\">CMSimple</a>";
   // besser:
   echo '<a href=http://www.cmsimple.org\" title="CMSimple">CMSimple</a>';

6. Parameter und Operatoren sollten mit Leerzeichen separiert werden.

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

   Es sollten Zeilenumbrüche und Einrückungen bei vielen Parametern oder Bedingungen verwendet werden.

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

7. Es sollte nicht zu tief verschachtelt werden und es werden kurze Code Zeilen empfohlen (max. 80 Zeichen sind zu bevorzugen).

   // 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);

   Zum Schreiben von kurzen Codezeilen können die einzelnen Zeilen mit einem "Punkt" direkt unter dem "=" verbunden (verkettet) werden.

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

8. Bei Funktionsnamen sollten besser lange und selbstsprechende Begriffe unter Verwendung von Unterstrichen oder camelCase als zu kurze Begriffe verwendet werden.

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

   Class Toy
   {
      //...
   }

10. Bei Arrays sollte die Zuordnung eingerückt werden:

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