Dokumentieren mit Patterns – Beispiele aus der Praxis

Print Friendly, PDF & Email

Baroque bookshelve details

Die Dokumentation eines Projekts in Form von Patterns zu schreiben, klingt etwas gewagt. Dabei sind sie eine sinnvolle Ergänzung zur üblichen Software-Dokumentation.

Vor kurzem habe ich erläutert, wie man Patterns selber schreibt. Indem man eine vorhandene Lösung in Form eines Patterns beschreibt, lernt man viel über das Problem, das man gelöst hat. Die Dokumentation von Software enthält üblicherweise umfangreiche Beschreibungen, wie die Software strukturiert ist – die Gründe, warum die Software genau so strukturiert ist und nicht anders, werden selten intensiv ausgeleuchtet. Dabei sind gerade die Begründungen für die getroffenen Design-Entscheidungen wichtig, damit eine Software auch von neu zu einem Team hinzugekommenen Entwicklern langfristig konsistent weiterentwickelt werden kann.

An dieser Stelle möchte ich zwei Beispiele aus einem Projekt vorstellen, die zeigen, wie Patterns in der Realität einer Softwaredokumentation aussehen können.

Common-Projekt

Das Backend bietet viele fachliche und technische Funktionen, vor allem enthält es die Geschäftslogik und stellt die Daten bereit, die das Frontend benötigt.

Wie erleichtern wir es den Frontend-Entwicklern, die richtige Funktionalität aus dem Backend zu verwenden?

Das Backend besteht aus mehr Diensten als das Frontend benötigt. Manche dieser Dienste dürfen nicht direkt aus dem Frontend heraus aufgerufen werden. Als Frontend-Entwickler möchte man nur diejenigen Dienste und Domänenobjekte sehen, auf denen der Zugriff erlaubt ist. Vor der vollen Komplexität der Backend-Implementierung sollte ein Frontend-Entwickler abgeschirmt sein.

Daher:

Alle fachlichen Schnittstellen, die vom Backend für das Frontend vorgesehen sind, sowie alle Domänenklassen liegen im Common-Projekt.

Das Common-Projekt wird sowohl vom Frontend wie vom Backend eingebunden, eine direkte Abhängigkeit vom Frontend auf das Backend existiert nicht. Somit ist klar geregelt, welche Funktionalität für das Frontend freigegeben ist. Nicht-freigegebene Funktionalität verbleibt im Backend-Projekt und ist im Frontend-Projekt weder sichtbar, noch erreichbar.

Der Vorteil dieses Ansatzes ist, dass die für das Frontend verfügbare Funktionalität das Backend klar definiert ist. Der Nachteil ist, dass Schnittstellen und Implementierungen der Services im Backend auseinander gerissen werden.

Protokollieren des Änderungsdatums

Bei vielen Entitäten ist es wichtig zu wissen, wann welcher Nutzer zuletzt eine Änderung vorgenommen hat.

Wie stellen wir sicher, dass beim Anlegen und bei jeder Änderung einer Entität Änderungsdatum und ändernder Nutzer gespeichert werden?

Manuell die entsprechenden Felder anzulegen und zu befüllen ist fehleranfällig, da dies bei jedem Service einheitlich programmiert werden müsste.

Daher:

Nutze die Schnittstelle Auditable mit der Embeddable-Klasse AuditInfo.

Die Schnittstelle Auditable kennzeichnet eine Entität, sodass das System die Audit-Informationen automatisch einträgt, wenn ein Objekt in die Datenbank geschrieben wird. Die Schnittstelle Auditable enthält eine Methode getAuditInfo, die ein AuditInfo-Objekt zurückliefern muss. In der Entitätsklasse muss ein passendes Feld deklariert und ein Objekt angelegt werden. Die schon existierenden Entitätsklassen können als Vorlage dienen.

Das automatische Setzen der Felder geschieht über einen JPA-EntityListener. Dieser Listener wird in der orm.xml deklariert und vom Persistenz-Provider vor jedem Schreiben in die Datenbank aufgerufen.

Der Vorteil dieses Ansatzes liegt darin, dass er transparent und einfach zu verwenden ist. Nachteile gibt es wenige – den SQL-Code zum Erzeugen neuer Entitäten muss alle benötigten Spalten konsistent enthalten.

Schreibe einen Kommentar