Coding Guidlines für ContentLion Plugins

Die Plugins von ContentLion sollen qualitativ gut sein, weshalb ich zum Start der Beta auch ein Bewertungssystem für Plugins erstellen werde. Darin wird von mir (oder später auch weiteren) unter anderen der Code getestet und bewertet.

Gut bewertete Plugins werden dann dementsprechend besser gelistet. Heute möchte ich schon einmal die Coding Guidlines für Plugins vorstellen (Einwände gerne im Kommentar). Diese werden dann später in die Dokumentation integriert.

Damals habe ich ja schon mal allgemeine Coding-Guidlines für ContentLion geschrieben, die aber noch etwas aufgefrischt werden müssen.

Hier also die neuen Regeln:

ContentLion intern

  • Alle Namen müssen mit plugin_pluginname_ beginnen. Dazu zählen unter anderen Klassennamen, CSS-Tags, JS-Befehle
    => Grund: Vermeidung von Namenskonflikten
  • Alle Texte müssen über die plugin-internen Sprachdateien gespeichert werden.
    => Grund: Einheitliche Internationalisierung

Vereinheitlichung

  • Es sollen immer nur doppelte Anführungszeichen eingesetzt werden
  • || statt or und && statt and
  • Einrückung erfolgt mit Tabs
  • Funktionen und Eigenschaften im Camel-Casing (Beispiel: readField)
  • Geschweifte Klammern müssen immer mit dem if, foreach, … in einer Zeile stehen

Kommentare

  • Jede Funktion und jede Klasse muss mittels PHPDoc dokumentiert sein.
    => Grund: Man kann den Code besser nachvollziehen und autocomplete nutzen
  • Keine Kommentare im Quellcode, der Quellcode muss an Hand der Variablen- und Funktionsnamen verständlich sein! (Ausgenommen PHPDoc)
    => Grund: Es ist besser an Hand der Namen zu erkennen, wie es funktioniert statt sich durch Kommentare abarbeiten zu müssen. So kann man z.B. If-Bedingungen in eigene Funktionen mit sprechenden Namen auslagern.

Übersichtlichkeit

  • Nur ein Befehl pro Zeile (andersrum ist ok)
  • Keine Mehrfachzuweisung in einem Statement (list und $a = $b = $c dürfen nicht genutzt werden)
  • SQL-Befehle müssen auch eingerückt werden
  • Jede Klasse muss ihre eigene Datei haben
  • Eine Datei darf maximal 700 Zeilen Code enthalten, eine Funktion maximal 50 Zeilen
    => Grund: Dadurch müssen automatisch Namen für Codeabschnittenn an Hand von neuen Funktionen und Klassen gegeben werden, was den Code besser strukturiert

Verschiedenes

  • Globale Variablen (global, $GLOBAL) sind verboten, stattessen statische Funktionen/Variablen nutzen
    => Grund: Man kann nacher besser nachvollziehen, welche Variable wie genutzt wird.
  • Programmiert wird komplett in Englisch.
    => Grund: Es kann leider nicht jeder Deutsch.
  • Variablen $_GET und $_POST dürfen nicht verändert werden
    => Grund: Man soll noch auf die Originaldaten zugreifen können
  • Keine nagierte Namensgebung (update statt no_update)
    => Grund: Kann sehr verwirrend werden
  • Funktionen die einen booleanschen Wert (true/false) zurückliefern, sollen mit is, has oder allow beginnen
    => Grund: Mann kann sofort erkennen was es macht
  • Funktionen müssen mit public , private oder protected deklariert werden
    => Grund: Sichtbarkeit ist sofort erkennbar
  • Es sollen Objekte statt associative Arrays (Arrays mit String als Key) verwendet werden, solange über die Keys immer gleich sind
    => Grund: Diese kann man durch Funktionen erweitern.
  • Für PHP-Tags wird <?PHP genommen
    => Grund: <? wird auch für andere Sachen verwendet
  • Der PHP –Code muss mit strikten PHP-Einstellungen funktionieren
    => Grund: Die Einstellungen können sich von System zu System unterscheiden
  • Der Html-Code soll mit HTML5 erstellt werden
    => Grund: Einheitliche Nutzung des gleichen Standards
  • Der Quellcode soll mit gängigen Browsern funktionieren (Kompatibilitätsliste folgt)
    => Grund: Funktionieren ist immer gut ;-)
  • Private Variablen und Funktionen werden kleingeschrieben, öffentliche Variablen großgeschrieben
    => Grund: Sichtbarkeit leichter erkennbar
  • Klassenvariablen müssen als protected deklaiert werden
    => Grund: So können auch Unterklassen darauf zugreifen. Öffentlicher Zugriff auf Klassenvariablen über Funktionen.
  • Keine Übergabe von Boolean-Parametern an Funktionen, stattdessen zwei verschiedene Funktionen benutzen
    => Grund: So kann man bei der Benutzung leichter erkennen, ob etwas ein oder ausgeschaltet werden kann.

Einwände oder Erweiterungsvorschläge? Her damit!

Wie bereits oben geschrieben, bin ich gerne bereit, die Guidlines nach euren Wünschen zu ändern – Mit guter Begründung natürlich. Durch die Richtlinien möchte ich mit den Plugins einen gewissen Qualitätsfaktor ansteuern. Denn 1 gut funktionierendes Plugin ist besser als 10 nicht so gute. Hoffe ihr versteht das.

Dieser Beitrag wurde unter Plugins veröffentlicht. Setze ein Lesezeichen auf den Permalink.

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *

*

Du kannst folgende HTML-Tags benutzen: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>