Kategorien
Projektwerkstatt: PHPDoc @layer
Diese Woche habe ich echt einen Lauf, was Kreativität angeht. Ich bin gerade dabei eine Applikation zu analysieren. Natürlich gibt es dort wie in jeder größeren Architektur Schichten. Das hilft ungemein wenn man sauber arbeiten will, aber wem sage ich das. Wir haben also Schichten in unserer Applikation und man darf nicht auf alle Schichten zugreifen, sondern nur auf ein paar erlaubt.
Ich habe mal irgendein Schichtenmodell aus dem Internet genommen. Wichtig ist dabei nicht der Inhalt sondern nur der Aufbau. Das ISO/OSI Modell kennt wahrscheinlich jeder. Egal wieder zum Thema. Wir haben Schichten, die miteinander kommunizieren dürfen und andere, denen es eben nicht gestattet ist.
Die meisten Klassen meiner Applikation kann ich sauber (genau) einer Schicht zuweisen. Wenn man jetzt einen PHPDoc Keyword hätte, dass einem anzeigt, zu welcher Schicht eine Klasse bzw. Methode gehört, könnte man ein paar schöne Dinge anstellen.
Na gut vielleicht keine Dinge, aber ein schönes Ding würde mir sofort einfallen. Wenn ich alles markiert habe, kann ich einen CodeSniffer Sniff programmieren, der den Code durchstöbert und mir rausfindet, wo ich gegen die Zugriffsregeln verstoßen habe. Ich könnte dabei zum Beispiel eine direkt erstelle DB Verbindung finden, ohne dabei über meine DB Abstraktion zu gehen.
Darstellen könnte man das über eine einfache binäre Matrix (darf/darf nicht). Vielleicht kann man auch einfach jedem Package eine Schicht in einem externen Dokument zuweisen, dann ist der Aufwand geringer.
Ich glaube es würde einem bei einem großen Projekt mir vielen Entwicklern auf jeden Fall helfen groben Unsinn zu vermeiden. Und außerdem würde es ein Tag geben, das ich erfunden habe. Auch wenn es sowas in Java bestimmt schon 100 Jahre gibt (nur geraten).
Ich sehe übrigens schon Eclipse Plugins vor mir. Eine Vision entsteht …
Ich höre schon ganz viele „aber hier muss ich doch..“ und „hier kann ich doch nicht anders, als…“ Aufschreie, wenn du das an einem lebenden Obkejt versuchst. Aber der Ansatz ist deshalb nicht weniger richtig. Sch***en viel Arbeit allerdings, die so herausgestellten Regeln dann im Nachinein zu befolgen..
Ich wäre übrigens wahrscheinlich für ein externes Dokument um @package und Schicht zu verknüpfen. Zum einen scheint, das weniger Aufwand zu sein, zum zweiten gönne ich dir keinen eigenen Tag! 😉
Aber vielleicht ist auch @use/usedby was?
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.uses.pkg.html
Ich spar mir mal das übliche: „Eigentlich sollte es bei einem gut durchdachten Aufbau gar nicht möglich sein sich zu vertun“.
Das suchen von „uses“ sollte normalerweise kein Problem darstellen: irgendwo gibt es bestimmt schon einen Sniff der Abhängigkeiten zählt. Dieser müsste die Abhängigkeiten lediglich noch protokollieren. Auch die @package bzw. @subpackage Annotations hast du beide schon. Ordne, wie von Christian angedeutet, die Packages und Sub-Packages in einer Konfigurationsdatei einer Schicht zu. Wir benutzen übrigens @subpackage dafür.
Man könnte es statt an einen Sniff zu schreiben auch an die Unit-Test anbinden: mit einem eigenen Autoloader. Dieser muss eigentlich nur protokollieren welche Datei er nachlädt und welche Klasse das verursacht hat. Dann sollte man sofort sehen, wann jemand aus seinem Layer (bzw. seinem Verzeichnis) heraus in ein fremdes Package springt.
Normalerweise fallen solche Dinge beim Unit-Tests aber sowieso auf, weil dort jeweils nur eine einzelne Schicht getestet wird und die anderen Schichten gar nicht initialisiert sind (oder besser: sein sollten).
Ein guter Unit-Test sollte dem Entwickler somit sowieso krachend um die Ohren fliegen, wenn er die Schichtgrenzen verletzt. Wenn das nicht passiert, sollte man sich eher die UnitTests nochmal zur Brust nehmen.
Doxygen hat u.a. die Möglichkeit der Gruppierung. Das wäre vielleicht eine Alternative.
http://www.doxygen.nl/grouping.html
Apropos UnitTests: der Nächste der mir so einen Testfall abliefert und behauptet er sei fertig, kriegt von MIR was krachend um dir Ohren!
function testAdd() {
$this->assertType(‚int‘, add(1, 1));
}
@Tom: Arbeitest du wirklich in einer Firma, in der solche Probleme nicht existieren? Neue Mitarbeiter oder unter Zeitdruck stehen Kollegen übersehen nunmal oft die Hierarchie, in viele Fällen gibt es auch gar kein Schichtenschaubild, an das man sich halten kann. Würde mich echt interessieren, wie das bei euch ist.
@Christian: Das was du hörst ist eine Workaround-Mentalität, die wohl ein größeres Problem als das durchbrechen der Schichten ist.
@Nils wir haben damit keine Probleme. Die Kollegen arbeiten mit Plugins. Sie können gar nichts falsch machen. An die anderen Schichten kommen sie rein technisch gar nicht erst heran.
Da müssten Sie schon absichtlich die Template-Engine aushebeln und mit echo() arbeiten. Wer das macht kriegt dann aber wirklich was auf die Finger.
Einen Controler gibt es nicht – alles virtualisiert. Was übrig bleibt sind quasi leichtgewichtige Services. Vielleicht 20-100 Zeilen Code pro Service.
Eigentlich regeln die Annotations und Konfigurationsdateien fast alles und nehmen dem Entwickler einen Haufen Schreibarbeit ab.
Der gesamte PHP-Quellcode zum Erzeugen, Befüllen und Anzeigen eines Formulars heißt.
/**
* @template edit
* @type default
*/
public function editFoo()
{
return true;
}
Und dazu ein Template in dem nichts steht außer:
{create template=“edit“ table=“foo“ on_edit=“writeFoo“}
Ernsthaft: that’s it!
Nicht, dass man es nicht auch komplizierter machen könnte, falls man will.
Wir haben eher Probleme damit, dass Leute Kopien von Code oder Dateien anfertigen statt sie wiederzuverwenden. Falscher Umgang mit Third-Party-Bibliotheken. Oder aber man macht es sich unnötig kompliziert.
Und natürlich die Dauerthemen Sicherheit, Qualität von Dokumentation und UnitTests. Aber in diesem Punkt reden sich sicher so manche Entwickler den Mund fusselig.