Entwickler: Styleguide

Styleguide

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

Sprache

• 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.

Entwicklung

• 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.

Dokumentation

• Einleitende Kommentare für die Funktionsbeschreibung sollten nicht vergessen werden.
• In den Klassen und Libs jede Funktion mit PHPdoc-Kommentaren versehen (müssen mit /** beginnen!).
• 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!

Aufbau PHP-Dateien

• Einleitung mit Lizenz
• Ausgabe von HTML nicht im PHP Script vornehmen, dazu Templates (smarty) nutzen!

Coding style

• Der Code sollte den Empfehlungen von PSR-1 und PSR-2 folgen.
• Der Code soll PHPdoc zur Dokumentation benutzen.

Klassen und Funktionen

• Sich wiederholende Funktionen bitte in Klassen oder Libraries auslagern.
• Alle Klassen müssen einem Namespace zugeordnet sein. (Meistens \PartDB)
• 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.
• Klassen müssen im Ordner lib/ abgelegt werde, Dateien mit globalen Funktionen in den Ordne inc/
• 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.