MSP: HÜ Forum

Aus THM-Wiki
Wechseln zu: Navigation, Suche


Diese Wiki-Seite dient zur Dokumentation der Hausübung "Forum", die im Rahmen des Moduls "Methoden des Softwareentwicklungsprozesses (MSP)" an der Fachhochschule Gießen-Friedberg im Wintersemester 08/09 bearbeitet wird. Verantwortlich für die Hausübung sind Jochen Woidich und Christian Weber.

Reverse Engineering

Dieser Abschnitt dient zur Dokumentation des durchgeführten Reverse-Engineerings.

Herkunft des Quellcodes

Große Teile des Quellcodes der Modulgruppe "Forum" stammen aus dem inzwischen aufgegebenen OpenSource-Projekt "ThWBoard" und wurden zur Integration in eStudy entsprechend angepasst. Das letzte Release von ThWBoard (Version 2.84) ist im Januar 2007 erschienen [1], die Quellen des Forums von eStudy sind in den Kommentaren auf Februar 2004 datiert und entstammen vermutlich aus der bereits im November 2003 erschienen Version 2.83. Der relativ kleine Versionsunterschied (.83 -> .84) lässt darauf schließen, dass in dem Zeitraum von 4 Jahren keine größeren Fehlerkorrekturen mehr am Mutterprojekt vorgenommen wurden und die Änderungen somit auch wenig relevant für den Fork in eStudy sind.

Datenbankschema

Mit MySQL Workbench generiertes Datenbankschema.
Tabelle Verwendung
forum_avatar Namen und URLs aller Avatare
forum_ban Von bestimmten Kurs-Foren verbannte Benutzer.
forum_bannedwords
forum_registry
forum_registrygroup
forum_category
forum_lastvisited Zeitpunkt des letzten Besuchs eines Boards durch einen bestimmten User
forum_group
forum_groupboard
forum_subscribe
forum_thread Alle Threads
forum_post Alle Posts
forum_board Alle Boards
forum_user Forum-spezifische Benutzerinfos und Flags


Dokumentation

Mit Doxygen generierte Dokumentation der modulspezifischen Quelltexte.

Use Cases

Bei der Use Case Analyse wurden folgende Benutzer-Rollen betrachtet: Administrator, Dozent, Student und Gast. Für jede Benutzerrolle wurde ein eigenes Use Case Diagramm erstellt (zur besseren Übersicht).

Administrator

Admin-usecases.png


Dozent

Alle dargestellten Use Cases beschreiben die Möglichkeiten eines Dozenten innerhalb des Forum-Moduls in seinem eigenen Kurs.

Dozent-usecases.png


Student und Gast

Die hier dargestellten Use Cases treffen sowohl für die Benutzerrolle Student als auch Gast zu. Das Diagramm zeigt sämtliche Use Cases bei maximaler Foren-Berechtigung. Die Berechtigungen werden vom Administrator oder Dozenten erteilt und können für beide Rollen separat eingestellt werden.

Student-usecases.png


Klassendiagramme

Die folgenden Diagramme wurden mit Enterprise Architect erstellt und zeigen die speziell für das Modul "Forum" definierten Klassen.
Alle nicht modulspezifischen Abhänigkeiten, die außerhalb des Modul-Verzeichnisses liegen, wurden ebenfalls mit in die Diagramme aufgenommen.

  • forum/classes

  • forum/classes/distribution

  • forum/classes/misc

  • forum/admin/classes

Software-Metriken

Code-Coverage

Der aktuelle Code-Coverage-Index des Moduls liegt bei 63%. Diese Zahl beinhaltet bislang lediglich die Modulklassen. Zu Beginn waren keine Unittests vorhanden. Sämtliche Test wurden extra für die Software-Metriken erstellt.

C.R.A.P.-Index und Zyklomatische Komplexität

Bei der Durchsicht der restlichen Metriken fallen nur wenige Methoden mit recht hoher Zyklomanischer Komplexität (>=10) auf.
In allen Fällen ist ein hoher C.R.A.P-Index bei Methoden, die eine niedrige Zyklomatische Komplexität aufweisen, auf eine sehr geringe Code-Coverage der entsprechenden Methode zurückführen.

Folgende Methoden sind bei der Analyse der Metriken aufgrund ihrer Komplexität hervorgestochen:

Methode Zyklomatische Komplexität C.R.A.P-Index
ForumAutomation::updateUser 27 756
ForumAutomation::deleteCourse 16 272
ForumAutomation::newCourse 13 182
Permission::has_permission 10 110
upload::fileExtOK 10 110

Performance-Tuning

Die Modulgruppe "Forum" wurde bereits von Frank Staudt im Rahmen seiner Diplom-Arbeit "Performance-Tuning und SLA-Monitoring LAMP-basierter Webapplikationen am Beispiel der Lernplattform eStudy" ausführlich auf Bottlenecks überprüft und dahingehend optimiert. Seine Funde und Ergebnisse sind in Kapitel 12.5 im verlinkten Dokument beschrieben.
Es konnten weder durch die Analyse der Ergebnisse von xdebug (visualisiert mit kcachegrind), noch durch das manuelle durchforsten der Quellen neue Bottlenecks aufgespürt werden. Auf Mikro-Optimierungen wurden verzichtet.

Bad Smells

Bei der Analyse der gesammelten Metriken und einer groben Durchsicht der Quelltexte sind folgende Bad Smells aufgefallen.

Smell Klasse / Methode / Datei Kommentar
Large Class ForumAutomation Große Klassen. Was ist "groß"? Aufgenommen: LOC > 400
Long Method ForumAutomation::updateUser (74)
ForumAutomation::deleteCourse (85)
ForumAutomation::newCourse (75)		 Lange Methoden. Auch hier: Was ist "lang"? Aufgenommen: LOC > 50
Comments In beinahe allen Klassen/Funktionen/Skripten Überflüssige Kommentare die nicht beschreiben was passiert und nicht warum es passiert.
Dead Code In beinahe allen Klassen/Funktionen/Skripten Toter (meist stumpf auskommentierter) Code
Shotgun Surgery In beihnahe allen alleinstehenden Skripten Es wird massiv auf superglobale Arrays ($_GET, $_POST, besonders $_SESSION) zurückgegriffen. Sollten sich die zum Zugriff genutzten Schlüssel einmal ändern sind ebenso massive Änderungen am Code notwendig.
Switch Statement In vielen Klasse/Funktionen switch-Statements

Sonstiges:

  • Großteil der Logik nicht in Klassen gekapselt, sondern in Funktionen (Datei: class.functions.inc.php) oder direkt in alleinstehenden Skripten.
    • Grund: Die ursprünglichen Modul-Entwickler haben vorhandenen Code genutzt, der einfach nicht objektorientiert ist -> Nicht ohne großen Aufwand änderbar
  • Keine saubere Trennung von Darstellung und Logik.
    • HTML-Ausgabe direkt im Programmfluss.
    • Texte fest einprogrammiert -> Nicht ohne großen Aufwand internationalisierbar.
    • Darstellung nicht ohne weiteres anpassbar.
  • Teileweise mehrere Klassen (zusammen mit Funktionen!) in einer Datei (Datei: class.functions.php, Klassen: Template, Permission, upload)
  • Kein durchgängiger Stil
    • Kommentare
    • Einrückung
    • Bezeichner
    • ...
  • Unvollständige Dokumentaion

Erweiterung und Refaktorisierung

Erweiterung

Im Rahmen der Veranstaltung soll das Forum um ein neues Feature ergänzt werden.

Problemstellung & Motivation

eStudy verfügt über eine konfigurierbare Sitzungs-Verwaltung, die inaktive Benutzer nach einer vorgegebenen Zeit automatisch abmeldet. Obwohl dieser Mechanismus nötig und sinnvoll ist, hat er gewisse Tücken: Schreibt ein Benutzer lange Zeit an einem neuen Beitrag zum Forum ist es möglich, dass er dabei seine Sitzungsdauer überschreitet ohne es zu bemerken. Erst beim Abschicken des Beitrags stellt der Benutzer fest, dass er abgemeldet wurde. Seine Arbeit geht, wenn er sie nicht manuell gesichert hat, verloren.
Da solche Vorkommnisse äußerst ärgerlich sind, soll ein Feature entwickelt werden, dass den Benutzer entweder früh genug warnt, oder das Problem anders löst. Das automatisierte Aufrechterhalten der Sitzung ist jedoch keine mögliche Lösung.
Da es sich hierbei um ein generelles Problem handelt und nicht nur das Forum betrifft, sollte die zu implementierende Lösung möglichst allgemein gehalten werden, damit sie auch in anderen Module genutzt werden kann.

Variante 1 - "Timeoutcounter"

Die erste vorgeschlagene Lösung für das Problem ist ein kleines Fenster innerhalb der Seite, das sich öffnet, sobald ein Benutzer anfängt einen neuen Beitrag zu schreiben. Im diesem Fenster wird angezeigt, wie lange dem Benutzer noch bleibt, bis er automatisch abgemeldet wird.
Beim Öffnen des Fensters fragt ein JavaScript via AJAX den Server nach der vom Administrator eingestellten maximalen Dauer bis zur automatischen Abmeldung. Die so erhaltene Zeit in Minuten wird im Fenster angezeigt und anschließend entsprechend heruntergezählt. Dies geschieht völlig clientseitig. Bleiben nur noch wenige Minuten könnte das Fenster die Zeit optisch hervorheben (z.B. durch eine markante Farbe, Blinken...), um den Benutzer deutlich zu warnen.

Diese Variante wurde vollständig umgesetzt.

Features

  • Anzeige der verbleibenden Sitzungsdauer in Minuten
  • Optische Hervorhebung der restlichen Sitzungsdauer, sobald nur noch 5 Minuten verbleiben
  • Warnung und Hinweis, die eingegebenen Daten manuell zu sichern, sobald die Sitzungszeit abgelaufen ist
  • Zwei Anzeigemodi
    • Balken am unteren Fensterrand (Standard. Wird eingeblendet sobald ein durch das Plugin überwachtes Eingabeelement fokussiert wird)
    • Fenster innerhalb der Seite (Sobald der Balken vom Benutzer verschoben wird)
  • Verschiedene Interaktionen, einzeln (de-)aktivierbar
    • Fenster/Balken schließbar
    • Fenster skalierbar
    • Fenster innerhalb der Seite verschiebbar
  • Unabhängig von der Modulgruppe "Forum", kann also überall innerhalb von eStudy verwendet werden.

Verwendung

Der Timeoutcounter kann auf jeder beliebigen Seite eingebunden werden werden. Dazu muss zuerst das (bereits von eStudy zur Verfügung gestellte) JavaScript-Framework jQuery [2] eingebunden werden, danach kann der als jQuery-Plugin implementierte Timeout-Counter geladen werden.

Das Einbinden von jQuery geschieht am besten über das von eStudy bereitgestellte Array $JS_INCLUDE, indem ein neues Feld mit dem Inhalt "jQuery" angehängt wird. Zu beachten ist, dass dies vor dem Einbinden von init.php geschieht, da das Statement sonst keinerlei Wirkung zeigt.

Um schließlich den Timeoutcounter zu aktivieren muss einzusätzliches Script geladen werden. Auch zu diesem Zweck existiert in eStudy eine einfache Möglichkeit: Das Objekt $eStudyPage verfügt über die Methode appendJavaScriptFile, mit der ein Script an der richtigen Stelle injiziert werden kann. Als Parameter wird ein valider HTML-<script>-Tag erwartet, der zuerst konstruiert werden muss.
$eStudyPage existiert erst nach dem Einbinden von header.php, der Methodenaufruf muss also danach erfolgen.

Beispiel zum Einbinden des Timeoutcounters: 

...
// Defines (z.B. PATH_TO_ROOT)
...
$JS_INCLUDE[] = "jQuery";
...
// Includes (z.B. header.php)
...
$js = "<script type='text/javascript' src='" . PATH_TO_ROOT . "common/js/jquery.timeoutcounter.js'></script>\n";
$eStudyPage->appendJavaScriptFile($js);
...

Der Timeoutcounter wird im Forum bereits genutzt. Weitere Beispiele zur Verwendung sind also den Quellcodes des Forums zu entnehmen (z.B. reply.php).

Das Plugin unterstützt eine Reihe von Optionen, die am Anfang der Datei jquery.timeoutcounter.js gesetzt werden können. Folgende Optionen werden unterstützt:

Option Bedeutung Default-Wert
titleText Text in der Titelleiste des Fensters Zeit bis zur automatischen Abmeldung
counterText Text im Inhaltsbereich des Fensters Ihnen bleiben noch %m Minuten. Speichern Sie Ihren Beitrag rechtzeitig ab, um den Verlust Ihrer Arbeit zu verhindern! (%m wird durch die Anzahl der verbleibenden Minuten ersetzt!)
warningText Text im Inhaltsbereich des Fensters, der angezeigt wird, wenn die Sitzung abgelaufen ist Ihre Sitzung ist abgelaufen! Sichern Sie Ihren Beitrag, bevor Sie sich erneut anmelden!
closable Soll das Fenster schließbar sein? true
resizable Soll das Fenster skalierbar sein? true
draggable Soll das Fenster verschiebbar sein? true
minHeight Minimale Höhe des Fensters in Pixeln 100
minWidth Minimale Breite des Fensters in Pixeln 150

Variante 2 - Wiederherstellung der Eingabe nach erneutem Anmelden

Der Benutzer wird nach dem Absenden seines Beitrages aufgefordert, sich erneut anzumelden, falls seine Sitzung bereits abgelaufen ist. Nach der Erfolgreichen Anmeldung wird er wieder zu dem Formular umgeleitet, das er abzuschicken versucht hat. Die eingegebenen Daten bleiben erhalten. Beim erneuten Abschicken des Formulars wird sein Eintrag in die Datenbank übernommen.

Diese Variante wurde aus folgenden Gründen nicht umgesetzt:

  • Eine komplett clientseitige Implementierung des Features ist derzeit nicht sinnvoll umsetzbar, da die dafür verfügbaren Technologien (z.B. HTML5 Web Storage) noch von keinem Browser vollständig implementiert werden. Ältere Browser implementieren die benötigten Schnittstellen gar nicht.
  • Eine serverseitige Umsetzung wäre extrem aufwändig gewesen und hätte den geplanten Umfang der HÜ um ein vielfaches überschritten.

Unittesting

Javascript bietet im Bereich Unittesting einige Frameworks. Nachfolgend werden einige Frameworks aufgelistet.

  • FireUnit - ist eine Firefox Extension um Unittest zu erstellen. Es läuft allerdings nur unter Firefox. Ausserdem benötigt es das Firebug-Plugin. Die Testergebnisse sind lediglich unter Firebug sichtbar.
  • JSUnit - ist eine Portierung des JUnit Frameworks nach Javascript. JSUnit ist browserunabhängig und kommt mit einem Test-Runner worin man seine Test laufen lassen kann. Die Testdateien müssen allerdings auf einem Server laufen. Die Ausgabe erfolgt dann im Browserfenster.
  • JSSpec - im Gegensatz zu JsUnit müssen die Testdateien nicht auf einem Webserver laufen.
  • QUnit - ist das Unittesting-Framework von jQuery. Mit diesem Framework kann man allerdings auch anderen Javascript Code testen.

Überarbeitung

Neben dem neuen Feature sollen einige kleinere Bugs gefixt werden.

  • Neue Icons für (un-)gelesene Foren
  • Bugfixes
    • Die Funktion "Alle Boards als gelesen markieren" funktioniert nicht richtig. Die Board-Icons ändern sich nicht.
    • In der Themenansicht werden dem Benutzer auch Optionen (z.B. Thread schließen) angezeigt, zu denen er gar keine Rechte hat.
    • Noch irgendwas...
  • Zusätzliche Arbeiten

Die neuen Icons wurden zwar im Forum-Modul hinterlegt, allerdings nicht in die CSS-Sprites des Standard-Style übernommen. Hierfür hätte man neue Sprites generieren lassen müssen. Dazu hätten wir allerdings die Einstellungen der bisherigen Sprites, sowie alle bisher verwendeten Icons benötigt. Eine Rücksprache mit Herrn Thelen ergab, dass eine solche Dokumentation bzw. eine Zip Datei mit den bisherigen Icons nicht existiere. Aufgrund von Zeitmangel, haben wir dies nicht umgesetzt.

Ein Vorgehen hinsichtlich der XP-Methode (zuerst Unittests schreiben, dann implementieren) war bei den Bugfixes nicht möglich. Um einen Unittest für die entsprechenden Fixes schreiben zu können, hätten wir zunächst einmal alle möglichen Parameter analysieren müssen. Ein weiterer Grund weshalb wir keine Unittests schreiben konnten war, dass ein Großteil der Funktionalität über einfache Skripte geregelt wurde und nicht über Klassen. Wir entschlossen uns sämtliche Bugfixes von Hand zu testen und keine Unittests zu implementieren.

Liste der veränderten Dateien

Kurzfassung

Allgemein

Klassen

Tests

Templates

JavaScripts

Stylesheets

Bilder

Liste der Dateien, die unter Umgehung der Pre-Commit-Hooks eingecheckt wurden

Folgende Dateien wurden unter Umgehung der Pre-Commit-Hooks (//@codingStandardsIgnoreFile) in den Branch eingecheckt.
Genannt sind jeweils das entsprechende Changeset, die betroffenen Dateien und der Grund der Umgehung.

Abgerufen von „https://wiki.thm.de/w/index.php?title=MSP:_HÜ_Forum&oldid=15945“