Programmiervorgaben

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Wie in jedem größeren Softwareprojekt gibt es auch für neue eStudy-Module einige Programmiervorgaben. Auch wenn diese nicht von allen Altmodulen berücksichtigt wurden, heißt das nicht, dass man sie bei der Neuentwicklung ignorieren darf.

Grundsätzlich gilt: Vermeiden Sie das "Kochen des eigenen Süppchens".

Förmliches

  • Zur Einrückung sind nur Tabs erlaubt, keine Spaces.
  • Alle Textdateien verwenden die Zeichenkodierung UTF-8.
  • Die Zeilen müssen mit einem \n beendet werden (Unix-Zeilenendung).
  • Es dürfen keine Umlaute verwendet werden. Zum Beispiel: Statt ä ist ae zu verwenden, ss statt ß usw.
  • Jede Klassen-Datei enthält nur eine Klasse.
  • Es werden keine Funktionen, sondern nur Methoden (also gekapselt in Klassen) verwendet.
  • Klassen-Dateien werden nach folgendem Muster benannt: class.<klassenname>.inc.php und liegen im Verzeichnis classes im Modulgruppen-Verzeichnis.
  • Interface-Dateien beginnen mit "iface" an Stelle von "class"
  • Alle Dateien, die includiert werden, erhalten die Endung .inc.php.
  • Datei- und Verzeichnisnamen werden klein geschrieben, ausgenommen sind hier mkf-Dateien.
  • Datei-, Verzeichnisnamen, Variablen, Konstanten etc. und Quellcode-Kommentare auch SVN Commit-Kommentare sind auf Englisch zu verfassen
  • Klassen werden mit require_once eingebunden. Da require_once keine Funktion ist (und ebenso auch require, include_once und include), dürfen keine öffnende und schließende Klammern gesetzt werden.
  • Die Entwicklung muss kompatibel zu PHP 5 (z.B. __construct(..) für den Konstruktor einer Klasse verwenden) und MySQL 5 sein.
  • Wenn Ihr Modul Uploads ermöglicht, verwenden Sie zum Speichern bitte den Pfad, der in der Variablen $settings["upload_path"] steht. In der Regel ist das upload/. Ihr Modul muss innerhalb dieses Ordners einen Unterordner mit der Bezeichnung Ihres Moduls anlegen.

Konventionen

  • Die sog. PHP-Short-Tags sind nicht erlaubt. Statt <? ist <?php zu verwenden. Demnach ist auch <?= verboten und durch <?php echo zu ersetzen.
  • In allen Templates kommen keine geschweiften Klammern sondern die alternative Schreibweise zum Einsatz (if/endif, foreach/endforeach usw.):
// Falsch:
<?php if(expr) { ?>
  ...
<?php } ?>
// Richtig:
<?php if(expr): ?>
  ...
<?php endif; ?>
  • Am Ende einer Datei darf kein schließender PHP-Tag stehen.
  • Auskommentierter Code muss entfernt werden. Dank Versionskontrolle geht dieser Code nicht verloren und kann bei Bedarf jederzeit wiederhergestellt werden.
  • Geschweifte Klammern stehen auf der gleichen Zeile wie der Code (One True Brace Style).
  • Die Sichtbarkeitsattribute public, protected und private sind immer anzugeben.
Namensgebung
  • Für Klassennamen wird die so genannte CamelCase-Schreibweise verwendet. D.h. sie beginnen mit einem Großbuchstaben und jeder weitere Wortteil ebenfalls.
  • Gleiches gilt für Methoden-Namen und Attribute, diese beginnen aber mit einem Kleinbuchstaben.
  • Ebenso müssen Variablen in camelCaseSchreibweise benannt werden.
Leerzeichen

Es sind keine Leerzeichen an den folgenden Stellen erlaubt:

  • Arrays: Richtig: $a[0]; Falsch: $a [0]; $a[ 0 ];.
  • Funktionsaufrufe: Richtig: f(1, 2);. Falsch: f( 1, 2 ); f (1, 2); f ( 1, 2 );
  • Mehrzeilige Funktionsaufrufe:
// Richtig:
f(
    1,
    2
);
  • Statische Aufrufe: Richtig: Klasse::funktion(). Falsch: Klasse :: funktion().

Nutzer von Zend Studio können auf den eingebauten Formatter zurückgreifen, um den Code automatisch an einige der Konventionen anzupassen. Dazu auf Preferences > PHP > Code Style > Formatter gehen und die eStudy Projektkonventionen importieren. Ein Beispiel, wie der formatierte Code aussieht, findet sich hier.

Erfahrungswerte und Best Practices

(noch zu sortieren und auszuformulieren; Ergebnis eines Brainstormings unter allen langjährigen eStudy-Administratoren)

Media:EStudy_Best_Practices.pdf

OO-Konzept: Wiederverwendung

Sie sollten bei der Entwicklung vermeiden, das Rad neu zu erfinden oder gar Funktionen aus anderen Klassen in Ihre eigenen zu kopieren. Versuchen Sie stattdessen, bereits vorhandene Funktionalität wiederzuverwenden. Änderungen an bestehenden Klassen zur Optimierung deren Wiederverwendbarkeit sind durchaus legitim.

Auf der anderen Seite sollten Sie selbst versuchen, Ihre Klassen auf möglichst große Wiederverwendbarkeit hin zu optimieren. Dazu gehört es zum Beispiel, die Funktionalität einer Methode möglichst auf die Erfüllung einer einzigen Aufgabe zu beschränken (z.B. nur das Auslesen eines Datenbank-Eintrags und nicht das Auslesen und anschließende Ausgeben).

Wenn Sie eine Methode entwickeln, die einen eher allgemeinen Zweck erfüllt, denken Sie darüber nach, ob Sie den Code nicht in einer der allgemein verfügbaren Utility-Klassen implementieren, von wo aus er leichter wiederverwendet werden kann. Sprechen Sie dies am besten mit einem erfahrenen Entwickler ab. Bevor Sie zu viele Fragen stellen, können Sie natürlich einen Wrapper um das Objekt schreiben oder in einer Kindklasse neue Funktionialitäten hinzufügen und dann Ihre Version "en bloc" in die gemeinsam verwendeten Klassen einfließen lassen.

Sicherheit

Die Gefahren durch Cross-Site-Scripting (XSS) oder SQL-Injektion werden immer größer. Da eine ausführliche Behandlung dieser Themen hier den Rahmen sprengen würde, lesen und verstehen Sie bitte den PHP Security Guide.

Mit der Data-Klasse ist ein grundlegendes Werkzeug zur sicheren Ein- und Ausgabe von Daten bereits in eStudy vorhanden. Die zwei am häufigsten benötigten Funktionen sind

  • Data::toHTML(): Maskierung zur Ausgabe von Daten an den Browser (inkl. Berücksichtigung der korrekten Kodierung von Zeichen).
  • Data::toMysql(): Maskierung zur Verwendung von Daten in SQL-Strings.

Zur genauen Beschreibung der Methoden siehe Klassen zur allgemeinen Verwendung.

Die Entwickler der Data-Klasse Andreas Nolden und Udo Güngerich haben außerdem eine Präsentation zum Thema EntwicklerInnen und Sicherheit verfasst.

Nota bene: Eine client-seitige Eingabevalidierung per JavaScript ist nicht ausreichend. Um den User-Komfort bei fehlerhaften Eingaben zu erhöhen, soll dennoch nicht auf eine Validierung auf der Clientseite verzichtet werden. Hierzu ist die JS-Bibliothek "really easy field validation" von Andrew Tetlaw einzusetzen, siehe web/common/js/validation.js.

SQL-Dateien

Benötigt Ihre Modulgruppe weitere Datenbank-Tabellen, müssen deren Definitionen in Form von .sql-Dateien im Modulgruppen-Verzeichnis vorhanden sein. Diese Dateien sollten den selben Namen tragen, wie das Verzeichnis selbst.

Zu beachten ist, dass die CREATE TABLE-Anweisungen kompatibel zu MySQL 5.0 sind. Die Standard-Zeichenkodierung von eStudy ist UTF-8, dies sollte bei jeder Tabelle angegeben werden. Von dieser Regel darf nur in begründeten Ausnahmefällen abgewichen werden. Zusätzlich ist InnoDB zu verwenden und nicht MyISAM, denn InnoDB unterstützt unter Anderem Fremdschlüsselbeziehungen und ACID-konforme Transaktionen.

Des Weiteren müssen die Tabellen einen einheitlichen Modulpräfix haben. Beispielsweise haben alle Tabellen des Forums den Präfix forum_.

Eine korrekte Anweisung sieht demnach so aus:

CREATE TABLE `praefix_tableName` (
...
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE utf8_unicode_ci;

HTML-Code und Design

Bis auf wenige begründete Ausnahmen sollen alle eStudy-Seiten XHTML 1.0 Strict valide sein. Verwenden Sie zur Überprüfung dieser Eigenschaft bitte den Browser Firefox und die beiden Firefox-Erweiterungen HTML-Validator (based on Tidy) und Web Developer Extension. Erstere dient der groben Orientierung, aber nur mit der Web Developer Toolbar erhalten Sie über Werkzeuge -> Lokales HTML überprüfen absolute Sicherheit.

Halten Sie den erzeugten HTML-Code möglichst schlank. Inline-Styles sollten vermieden werden und verwenden Sie so wenig Layout-Tabellen wie möglich. Achten Sie auf semantische Korrektheit (Überschriften, Listen etc.).

Ihre Entwicklung sollte in den Designs Basic, OSX und OSX Low ansprechend, aber dem restlichen Seitendesign angemessen dargestellt werden. In allen anderen Designs müssen Ihre Module weiterhin bedienbar sein.

Zur Einführung in XHTML und das CSS-Framework können Sie sich die Ausarbeitung und die Präsentation von George Parks Davie und Thomas Loreit ansehen.

Verwendung fremder Software

eStudy verwendet bereits Software anderer Autoren, genannt seien hier:

Scheuen Sie sich nicht, im Zuge der Wiederverwendung ebenfalls auf andere Software zu setzen. Voraussetzung dafür ist, dass die Software unter der GNU GPL oder einer ähnlichen freien Lizenz veröffentlicht wird und ihr Umfang ihrer geplanten Verwendung angemessen ist (bedenken Sie die zusätzliche Download-Zeit, die Anwendern und Entwicklern abverlangt wird).

Ist die Software von allgemeinem Nutzen für (spätere) eStudy-Module (wovon in der Regel auszugehen ist), sollte sie im common/classes/-Verzeichnis platziert werden. Besprechen Sie das bitte mit einem erfahrenen Entwickler.

Beachten Sie bitte außerdem, dass sich der Konfigurationsaufwand für den Endanwender in Grenzen halten sollte. Verwenden Sie wenn möglich die bereits in eStudy verfügbaren Einstellungen aus dem $settings-Array, z.B. für die Zugangsdaten zur Datenbank.

Weblinks

Vereinbarung

Den Programmierrichtlinien zugestimmt hat: jenkins Jhtr80 Cthl58 Pcvl72