13. Juli 2009

Coding Guidelines

in Extension

Coding Guidelines – schon mal irgendwo gelesen?
Wenn ich das bisher irgendwo gelesen habe, habe ich das Kapitel schnell übersprungen, denn die Funktion war mir oft wichtiger als der Code. Kennt ihr das? Dann nicht weiterspringen sondern weiterlesen…

Was sind Coding Guidelines?
Die CG definieren, wie TYPO3 Code, Dateien und Verzeichnisse strukturiert und formatiert sein sollten. CG liefern keine technischen Informationen und hilft nicht beim Programmieren.

Warum braucht man Coding Guidelines?
Vor allem zwei Ziele sollen mit standardisiertem Code erreicht werden:

  • Sicherheit
  • Lesbarkeit

In eigenen Worten würde ich sagen, dass die CG helfen sollen, sich in unbekanntem Code (und das kann durchaus der eigenen Code nach einem längeren Zeitraum sein) schnell und sicher zurechtzufinden. Das Einhalten der CG sichert eine skalierbare und sichere Erweiterung.

Interessiert mich das?
Jedenfalls sollte es dich interessieren, wenn du deine Extension veröffentlichen willst oder es bereits getan hast. Innerhalb der „Inspiring people to share“ Erweiterungen ist es durchaus üblich, das auch andere Entwickler einen Blick in den Code riskieren um diesen mit voran zu treiben. Machen wir es also nicht noch schwerer.

Die Vorher/Nachher Show
Klar könnte ich jetzt alle Punkte stichwortartig abtippen, aber die könnt ihr sicher schneller und besser in den Original CG nachlesen (siehe Link unten). Stattdessen mache ich eine kleine Vorher/Nachher Show.

Vorher:

< ?
class x {
  function xy ()
  {
    $a = "<div style="color: blue;">Das ist ein Text</div>";
    if ($b)
      $a = "<a href=\"index.php?id=$_POST["var"]\">$a</a>";
 
    mysql_connect($dbort,$dbuser,$dbpw);
    mysql_select_db($dbdb);
    $z=mysql_query("SELECT * FROM table");
    while($datenvondatenbank=mysql_fetch_array($z))
    {
      echo "Daten: $datenvondatenbank[links]";
    }
  }
}
? >

Nachher:

< ?php
  /* GPL Notice */
  /* Class explanation */
class tx_plugin_listView {
 
  /* Function explanation */
  function getDataFromDB($html) {
    $html .= $this->pi_getLL('value', 'alttext'); // description (HTML from Template)
    if ($this->piVars['uid']) { // description what this if is doing
      // Only using typolink or typolinkwrap
      // Output from piVars only
      // Rewrite Output (e.g.) with htmlspecialchars()
    }
 
    $res = $GLOBALS['TYPO3_DB']->exec_SELECTquery(
      '*',
      'table',
      '1'
    )
    // and so on
    // don't use echo - never ever
  }
}
// XCLASS Definition
? >

Die wichtigsten Punkte

  • ‚ statt „
  • GPL Hinweis nicht vergessen
  • XCLASS Definition nicht vergessen
  • < ?php statt < ?
  • Richtige Klammersetzung
  • Sinnvolle Benennung der Variablen, Klassen, Funktionen (CamelCase, English only)
  • Quelltextdokumentation (English only)
  • TYPO3 API statt direkter Zugriff auf Server Variablen
  • TYPO3 API statt eigener DB Zugriff
  • Typolinks statt eigener harter Links
  • Generell: Wie ist mein Code am einfachsten lesbar und am schnellsten verständlich
  • Generell2: Ein paar Zeilen mehr aber dafür mehr Übersicht ist immer besser

Links zum Thema

Cheers, Alex

PS: Ich mache auch nicht immer alles richtig, aber ich werde mich in Zukunft bemühen – versprochen 😉

6 Reaktionen zu “Coding Guidelines”

Kommentare abonnieren (RSS) oder TrackBack URL

Sehr guter Beitrag. Ich bin wohl genau deine Zielgruppe, hab mich bei fast jedem Punkt angesprochen gefühlt 🙂

Gruss

Vedran am 13. Juli 2009 um 15:27

Ein guter Beitrag! Der Link zu Dmitrys Artikel ist allerdings überholt, da es sich dabei um einen Preview handelte welcher inzwischen nochmal leicht verändert wurde. Hier gibt’s stattdessen das finale PDF: http://bit.ly/typo3cgl

Michael Stucki am 13. Juli 2009 um 21:10

(zur Verdeutlichung: Der Link zeigt auf die Extension im TER, welche das PDF ebenfalls enthält)

Michael Stucki am 13. Juli 2009 um 21:10

@Michael: Link oben habe ich geändert – thx!

Alex Kellner am 14. Juli 2009 um 15:59

Ich würde in diesem Zusammenhang auch gerne das FLOW3CGL Projekt (http://forge.typo3.org/projects/show/package-flow3cgl) erwähnen. Wir prüfen mit Hilfe des PHPCodeSniffer (aus dem PEAR Projekt) den Code automatisiert auf CGL Verstösse.
Das gilt natürlich nur für FLOW3 basierten Code (dort sind die CGL ja etwas anders) und alles lässt sich damit auch nicht prüfen.
Ich muss auch zugeben, dass ich momentan etwas hinterhänge meinen Branch fertig zu machen.

Cheers, Tim.

Tim Eilers am 15. Juli 2009 um 14:27

Gibt es da noch weitere Infos bzw. eine ausführliche Dokumentation der CGLs?

Typo3 Freelancer am 20. Juli 2009 um 15:30

Kategorien

Archiv