Unabhängig vom Architekturstil gibt es in jedem System Fachklassen bzw. ganz allgemein Informationsobjekte. Diese Objekte sind Datenspeicher (“etwas, das existiert”) oder repräsentieren einen aktuellen Zustand im System. Ein Informationsobjekt ist häufig mit einer Identität verbunden. Jede Software hat zum Ziel, Probleme innerhalb eines Fachgebiets – der Domäne – für ihre Nutzer zu lösen. Beim Domain-Driven Design (kurz DDD) geht es nicht nur um die technische Umsetzung, sondern auch um unsere Denkweise beim Entwurf des Systems. DDD zusammen mit CARDS+ eröffnet weitere Optionen. Informationsobjekte (Entity und Aggregate) aus dem DDD sind eine ideale Ergänzung zum entsprechenden Begriff im Glossar. Das ist immens wichtig für die Bildung eines gemeinsamen Vokabulars im Projekt. Die gemeinsame Sprache ist ein wichtiges Ziel von CARDS+ und DDD.

Spannend ist noch die Frage, ob wir bei der Implementierung des Domänenmodells die Begriffe ins Englische (der lingua franca der Entwickler) übersetzen sollen. Meine persönliche Empfehlung ist, keinen Begriff der Domäne zu übersetzen. Eine Übersetzung ins Englische widerspricht der Idee, dass Entwickler und Domänenexperten die selbe Sprache sprechen.

Motivation

Mit dem Baustein Entity wollen wir Informationsobjekte eines Systems beschreiben, weitestgehend unabhängig vom Architekturstil und der gewählten technischen Lösung. Dabei steht der fachliche Nutzen des Objektes im Vordergrund. In einem agilen Projekt können wir die Entscheidung für die technische Umsetzung getrost dem cross-funktionalen Team überlassen. Die Technologie für die Persistenz hat große Auswirkungen auf die Realisierung von Informationsobjekten und muss immer durch eine Entscheidung mit dem Baustein Decision begründet werden.

Wichtig ist, dass der Baustein Entity dafür gedacht ist, einem Informationsobjekt einen eindeutigen Namen zu geben. Der Name des Objektes wird auch im Code verwendet und schlägt damit die Brücke zwischen Wiki und Code. Die Struktur des Objektes beschreiben wir direkt in der Klasse (z.B. javadoc) oder formal mit einem XML-, AVRO– oder JSON-Schema.

Code und andere Artefakte der Entwickler in einem Code-Repository sind somit Teil der Dokumentation. Ein Leser der Produktdokumentation wird durch den Baustein Event in die Lage versetzt, den Code für eine Nachricht zu finden und zu verstehen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Zuerst erfasst man ein “Architecture Principle”, welches beispielsweise den Einsatz des Domain-Driven Design erklärt (das “Statement”) mit seinen Randbedingungen (das “Rationale”) und Auswirkungen (die “Implications”).

Das Kapitel 35 mit dem Titel “Architectural Artifacts” zeigt die unzähligen Möglichkeiten für die Darstellung des Systems (“View”) aus einer bestimmten Perspektive (“Viewpoint”) für einen bestimmten Aspekt der Funktionsweise des Systems (“Concern”).

Mit dem Begriff “Data Architecture” werden ganz konkret Diagramme vorgestellt, die geeignet sind, Informationsobjekte in allen Perspektiven, also statische und dynamische Sicht, darzustellen.

Quelle: TOGAF9 online documentation

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Nachrichten sind in erster Linie Datenstrukturen. Das Zusammenspiel der Bausteine wird in der Laufzeitsicht beschrieben.

Quelle: ARC42 online documentation

Definition

Beschreibung

Der Baustein Entity beschreibt ein Informationsobjekt des Systems und gibt ihm einen eindeutigen Namen. Der Name des Bausteins wird auch in der Implementierung im Code-Repository verwendet und schlägt damit die Brücke zwischen Wiki und Code.

Der Baustein Entity wird für Entwickler geschrieben. Ein Informationsobjekt ist eine Schnittstelle in einer service-orientierten Architektur.

Struktur

Abschnitt Steckbrief

Der Abschnitt enthält eine Tabelle mit Zeilen für eine Kurzbeschreibung und die Kategorie des Informationsobjektes.

ktip Der Steckbrief sollte so gestaltet werden, dass sich aus dem Namen, der Kurzbeschreibung und der Kategorie sehr leicht ein Katalog erstellen lässt. In Confluence nutzen wir das Makro Seiteneigenschaften für den Steckbrief. Der Katalog wird mit dem Makro Seiteneigenschaftsbericht erstellt.
Abschnitt Eigenschaften

Der Abschnitt listet die fachlichen Eigenschaften des Informationsobjektes auf. Jede Eigenschaft hat einen Namen und eine Beschreibung.

ktip Ein Informationsobjekt hat auch technische Eigenschaften, z.B. eine techische ID. Diese technischen Eigenschaften werden mit dem Baustein Spec als gemeinsames Konzept beschrieben.
Abschnitt Identität

Der Abschnitt zählt jene fachlichen Eigenschaften auf, mit denen das Informationsobjekt eindeutig identifiziert wird. Für den Fall, dass ein Informationsobjekt keine Identität hat, wird hier ein Leervermerk eingetragen.

Abschnitt Spezifikation

In diesem Abschnitt befindet sich die exakte Definition des Informationsobjektes, während die Abschnitte davor ein Verständnismodell für das Informationsobjekt beschreiben. Eine konkrete Implementierung kann im Detail von diesem vereinfachten Modell abweichen. Eine Implementierung muss nicht alle Attribute oder Elemente realisieren und kann weitere Attribute hinzufügen, wenn es für die Implementierung notwendig ist. Die konkreten Datentypen werden ausschließlich in der Spezifikation festgelegt.

ktip Der Abschnitt liegt in der Verantwortung des Entwicklerteams. Es bietet sich an, ein Artefakt (z.B. eine Schemadefinition) direkt aus dem Code-Repository zu verwenden und Confluence für die Veröffentlichung der Inhalte zu nutzen.