Entwickler: Styleguide

Styleguide

Wie alle größeren Projekte haben wir auch ein paar Richtlinien für die Programmierung aufgestellt.

Alle Kommentare sind in Englisch zu verfassen.
Deutsche Kommentare sind entsprechend zu kennzeichnen und möglichst rasch ins Englische zu übersetzen.
Kommentare sind nicht überflüssig, sondern notwendig!
Kommentare sollen nicht offensichtliche Dinge beschreiben, sondern zum allgemeinen Verständnis des Codes beitragen.

PHP 4 ist veraltet und wird nicht mehr unterstützt. Es muss daher keine Rücksicht genommen werden auf Versionen vor PHP 5.3.
Alle neuen Funktionen werden in den Branches zuerst getestet und dann in die offizielle Version übernommen.
Kennzeichnung von stable, unstable und non public (oder ähnlich)-Versionen. Diese Kennzeichnung wird nur für die gepackten Archive genommen und nicht für die Entwicklerversionen im Repository.

Einleitende Kommentare für die Funktionsbeschreibung sollten nicht vergessen werden.
In den Klassen und Libs jede Funktion mit Doxygen-Kommentaren versehen (müssen mit /** beginnen!).
Die wichtigsten Doxygen-Befehle findet man in der "Doxygen Quick Reference".
Nach Änderungen am System muss das Wiki ggf. angepasst werden, oder zumindest als "ToDo" vermerken dass es noch gemacht werden muss.
Für Dinge, die noch zu tun sind, immer den Befehl @todo benutzen!

Die Einrückung wird mit 4 Spaces vorgenommen. Keine Tabs verwenden (ev. eigenen Editor entsprechend konfigurieren)!
Öffnende und schliessende geschweifte Klammern in einer eigenen Zeile.
Jeder Block innerhalb geschweifter Klammern einrücken.
Ausnahmen für einzeilige Blöcke. Auf Klammern sollte der Lesbarkeit wegen nicht verzichtet werden.
IF-THEN-ELSE als ternärer Operator ((...) ? ... : ...) ist erlaubt, sollte möglichst aber nur bei der Zuweisung von Werten verwendet werden.
Arrays oder längere Strings so formatieren, das eine gute Lesbarkeit gewährleistet ist (ev. nur ein Element pro Zeile, schön untereinander).
Immer UNIX Zeilenende verwenden (\n)

Funktionen werden klein geschrieben und müssen selbst beschreibende Namen tragen.
Trennung der einzelnen Wörter erfolgt mit dem Unterstrich.
Für Variablennamen gilt das selbe wie für Funktionen.
Klassennamen werden Gross geschrieben (CamelCase).

Sich wiederholende Funktionen bitte in Klassen oder Libraries auslagern.
Namespaces sind möglich.
Klassen mit dem Konstruktur construct() für die Prüfung auf Abhängigkeiten der Klasse und eventuell fehlenden Funktionen versehen.
Includes am Anfang der Dateien bitte durch include_once() oder require_once() ersetzen. Ist meistens aber nicht notwendig wegen der Autoload-Funktion von PHP.
Debug-Meldungen einfügen für eine einfachere Fehlersuche. Dazu gibt es einen Debug-Mechanismus in lib.debug.php.
Exceptions verwenden (try...catch)! Das ermöglicht eine saubere Trennung zwischen Normalfall und Ausnahmefall.
In Klassen und Libraries bei Dateipfaden IMMER absolute Pfade verwenden, nie relative! Die absoluten Pfade werden denn wieder in relative Pfade umgewandelt wenn nötig.