Ich habe mich der Mitte eines mittelgroßen Projekts angeschlossen, das bereits seit mehreren Jahren läuft. Eines der Probleme ist, dass das Dokument, das die Architektur beschreibt, nie geschrieben wurde. Jetzt wurde mir die Aufgabe übertragen, die Architekturbeschreibung zu schreiben.

Während der Arbeit an diesem Projekt habe ich alle Informationen gesammelt, die ich zum Schreiben des Dokuments benötige. Da ich auch einige Features hinzugefügt habe, habe ich einige Codeteile identifiziert, die die beschriebene Architektur eindeutig brechen.

Beispielsweise sollte die GUI eine dünne Schicht ohne Geschäftslogik sein. Das wurde mir gesagt. Die Implementierung enthält viel Logik.

Mein Chef hat mich beauftragt, das Dokument zu schreiben, das die Architektur des Systems beschreibt. Zielgruppe sind aktuelle und zukünftige Entwickler, die an dem Projekt arbeiten. Ich muss beschreiben, was sein soll, aber ich muss auch die Abweichungen irgendwie beschreiben.

Wo soll ich diese Probleme beschreiben? Bugs-Tracking-Software? Oder sollte ich die Abweichungen der Implementierung von der Architektur in dem Dokument beschreiben, das die Architektur des Systems beschreibt?

Wenn Sie einen Entwurf oder eine Architektur eines Systems dokumentieren, das bereits erstellt wurde, sollte das Dokument beschreiben, wie es erstellt wurde und nicht wie es entworfen oder vorgesehen ist. Wenn die Architektur Kuriositäten oder Unstimmigkeiten aufweist, sollte dieses Dokument diese Probleme aufzeigen und dem Leser so weit wie möglich erläutern.

Wenn Sie in der Lage sind, Informationen von Personen zu erhalten, die von Anfang an an dem System gearbeitet haben (oder zumindest länger als Sie), ist es hilfreich, mehr Informationen darüber zu erfassen, was eigentlich beabsichtigt war und warum die Architektur und das Design davon abgewichen sind Absicht.

Am Ende des Tages sollte ein Designdokument als Leitfaden für den Code dienen. Wenn das Dokument einem neuen Entwickler nicht hilft, den aktuellen Status der Codebasis und deren Struktur zu verstehen, ist das Dokument nicht nützlich.

Dieses Dokument sollte ein lebendiges Dokument sein, das als Leitfaden für die zukünftige Planung und den Entwurf von Änderungen am System dient und dann im Rahmen Ihres Entwicklungsprozesses entsprechend aktualisiert wird. Da sich das Design im Laufe der Zeit ändert und weiterentwickelt, sollte das Dokument Entwicklern auch helfen, zu verstehen, warum die Dinge so sind, wie sie derzeit sind.

Wenn Sie Ratschläge zur Erfassung der Architektur suchen, gefällt mir der Ansatz, der im IEEE-Standard 1016-2009 IEEE-Standard für Informationstechnologie - Systemdesign - Softwaredesign-Beschreibung empfohlen wird . Es bietet eine sinnvolle Struktur für eine Entwurfsbeschreibung, mit der sowohl architektonische als auch detaillierte Entwurfsinformationen erfasst werden können.

Ich würde diese Abweichungen auch als eine Form der technischen Verschuldung betrachten. Es kann ein großes Unterfangen sein, vielleicht sogar ein kleines Projekt, um die Probleme zu beheben. Ich würde empfehlen, die Existenz der technischen Schulden sichtbarer zu machen. Wenn dies bedeutet, dass Sie Ihr Fehlerverfolgungs-Tool verwenden, können Sie dort ein oder mehrere Probleme anbringen. Wenn Sie ein anderes Tool zum Nachverfolgen von Vorschlägen und Verbesserungen für die Software verwenden, ist dies möglicherweise ein anderer Ort, an dem Sie es ablegen können.

Wenn Sie die Architektur des Systems formalisieren, ist es wichtig, dass Sie nicht nur den Wert verstehen, den die Architektur für den Tisch mit sich bringt, sondern auch verstehen und schätzen, was sie sein sollte.

Das Hauptziel von Software oder technischer Architektur besteht darin, die nicht funktionalen Anforderungen zu identifizieren, die durch die Qualitätsattribute realisiert werden, die die Systemarchitektur steuern .

Zu nicht funktionalen Anforderungen:

Eine nichtfunktionale Anforderung ist eine Anforderung, die Kriterien festlegt, anhand derer der Betrieb eines Systems beurteilt werden kann, und nicht bestimmte Verhaltensweisen. Sie stehen im Gegensatz zu funktionalen Anforderungen, die ein bestimmtes Verhalten oder bestimmte Funktionen definieren. Der Plan zur Umsetzung der funktionalen Anforderungen ist im Systementwurf aufgeführt. Der Plan zur Implementierung nichtfunktionaler Anforderungen ist in der Systemarchitektur beschrieben.

Im Allgemeinen definieren funktionale Anforderungen, was ein System tun soll, und nicht funktionale Anforderungen, wie ein System sein soll. ... Nichtfunktionale Anforderungen werden häufig als "Qualitätsattribute" eines Systems bezeichnet. Andere Ausdrücke für nichtfunktionale Anforderungen sind "Qualitäten", "Qualitätsziele", "Dienstqualitätsanforderungen", "Einschränkungen" und "Nicht-Verhaltensanforderungen".

Natürlich ist es bei einem Greenfield-Projekt sinnvoll, die architektonisch bedeutsamen Anforderungen zu identifizieren. Wenn Sie jedoch mit vorhandener Software arbeiten, sollten Sie so diszipliniert wie möglich vorgehen. Sie möchten nicht, dass Ihre Softwarearchitektur vom vorhandenen System beeinflusst wird.

Software-Architektur, um maßgeblich zu sein, muss wirklich 3 Dinge sein.

Deklarativ

Dies ist der Teil der Dokumentation, in dem Sie NICHT erklären, WAS IST, sondern wie die Dinge SEIN SOLLTEN. Wir tun dies durch die Verwendung verschiedener Architekturansichten des Systems. Wir definieren die Komponenten, die sein sollen, wie sie interagieren, und führen dann optional einen Drilldown in jede Komponente durch, um detailliertere Ansichten zu erhalten, in denen festgelegt wird, wie das System gestaltet werden soll.

Dies ist eine wichtige Unterscheidung. Das Systemdesign sollte durch die Systemarchitektur eingeschränkt werden, es handelt sich in der Tat um separate, aber verwandte Dinge.

Begründung

Das Grundprinzip Ihrer Softwarearchitektur ist das, was den getroffenen Architekturentscheidungen Legitimität und Autorität verleiht. Vielleicht wurde die Entscheidung getroffen, einen Pub / Sub-Ereignis-Listener über MQ zum Auslösen eines Batch-Jobs zu verwenden, und Sie stellen dies grafisch dar?

Warum wurde diese Entscheidung getroffen? Wir erklären, warum dies so ist, und verknüpfen unsere Erklärung mit nicht funktionalen Anforderungen, Qualitätsattributzielen oder architektonisch bedeutsamen Anforderungen. (Z. B. Jobs müssen asynchron und wiederholbar sein. Die Wartbarkeit als Qualitätsattribut bewirkt, dass im Falle eines Batch-Jobfehlers Jobs über eine MQ-Nachricht erneut gestartet werden können. Das System muss bei asynchroner Kommunikation keinen Nachrichtenverlust aufweisen. Usw.) ..)

Risiken

Nachdem Sie nun festgelegt haben, wie Architektur sein soll, und dies mit Ihrer Begründung bewiesen haben, können Sie jetzt Risiken für den aktuellen Status des Systems identifizieren, bei denen dies nicht der Fall ist.

(ZB wird die serverseitige Validierung auf dem clientseitigen Javascript-Code dupliziert. Dies stellt eine Verletzung des DRY-Prinzips dar und widerspricht dem Qualitätsmerkmal der Wartbarkeit. In diesem Bereich sind keine nicht funktionalen Anforderungen bezüglich der Leistung definiert.) ist kein Grund für das aktuelle Systemverhalten)

Ihre Risiken können auch grafisch darstellen, wo der aktuelle Status von der Architektur abweicht. Diesen Risiken kann das Entwicklungsteam jetzt entweder über seinen Projektplan oder durch Hinzufügen dieses Risikos zum Rückstand begegnen.

Sie müssen sich wirklich entscheiden, ob Sie die aktuelle Struktur des Projekts oder die gewünschte Struktur des Projekts oder beides dokumentieren möchten.

Sie können das Ziel dokumentieren, um die zukünftige Entwicklung in die gewünschte Richtung zu lenken, und die Abweichungen als Fehler melden (möglicherweise mit diesen Fehlern aus den relevanten Teilen des Dokuments verknüpfen). Oder Sie können die Realität dokumentieren, um eine Einführung / einen Überblick über den Code zu erhalten. Sie können auch beide Seiten gleichzeitig dokumentieren, sodass Sie gleichzeitig eine Anleitung für die zukünftige Entwicklung und eine genaue Beschreibung des aktuellen Codes an einem Ort haben. Alle sind vernünftig, je nachdem, wofür das Dokument gedacht ist, daher können wir Ihnen meines Erachtens nicht sagen, was Sie tun sollen.

Sie sollten auch bedenken, dass die gewünschte Architektur unter den Beteiligten möglicherweise nicht einheitlich ist (entweder weil sie unterschiedliche Dinge wollen oder weil einige von ihnen erkannt haben, dass einige ursprüngliche gemeinsame Wünsche unmöglich oder unpraktisch waren, und deshalb auf das Schreiben des vorhandenen Codes zurückgegriffen haben das weicht vom Ziel ab). Sie müssen also auch wissen, ob Sie befugt sind, zu entscheiden, was gewünscht wird, und wenn nicht, wer dies tut. Die bestehende Struktur hat zumindest die Tugend, dass es nur eine zu dokumentieren gibt!

Schreiben Sie in das Architektur-Design-Dokument, was eigentlich sein sollte, und öffnen Sie für jeden Konflikt ein Ticket im Bug-Tracker, das den Konflikt beschreibt. Der Kommentarbereich des Tickets bietet eine Plattform für die relevanten Personen, um diesen bestimmten Konflikt zu diskutieren.

Beachten Sie, dass die Auflösung jedes dieser Tickets darin bestehen kann, die Implementierung an das Design anzupassen. Sie können jedoch auch das Design an die Implementierung anpassen. Im Idealfall wird Ersteres bevorzugt, aber manchmal gibt es technische und / oder geschäftliche Einschränkungen, die es effizienter / pragmatischer / möglich machen, Letzteres zu wählen. In diesem Fall ist es möglicherweise eine gute Idee, auf das Ticket aus dem Architektur-Designdokument zu verweisen, damit zukünftige Leser, die nicht verstehen, warum diese bestimmte minderwertige Designauswahl gewählt wurde, die Diskussion im Ticket lesen und die Gründe dafür verstehen können es.

Ich würde gerne ein Architekturdokument schreiben, das in drei Hauptabschnitte unterteilt ist.

Die erste Einführung in das ursprünglich vorgesehene Design / die Architektur. Dies gibt neuen Entwicklern / Lesern die Möglichkeit, eine Vorstellung davon zu bekommen, was das System tun soll, und sollte offensichtlich an die Anforderungen / Anwendungsfälle usw. gebunden sein.

Der zweite Abschnitt sollte sehr genau erklären, was die Architektur eigentlich ist. Auf diese Weise können sich die neuen Entwickler / Leser einen Überblick über den aktuellen Stand und den Umgang mit der Software (und möglicherweise weiterer Dokumentation) verschaffen. Dieser Abschnitt sollte den Unterschied zwischen dem, was beabsichtigt war und der Realität deutlich machen, da dies höchstwahrscheinlich Dinge hervorheben wird, die entweder sehr falsch mit der ursprünglichen Architektur sind (hoffentlich nicht zu viele!) Und Bereiche, in denen Verknüpfungen / Hacks vorhanden sind (wahrscheinlich ein paar, wenn vorhanden) Es wurde ein hohes Maß an Druck auf das Entwicklerteam ausgeübt und die Anforderungen werden nicht erfüllt, oder die Software sieht allmählich „schlecht“ aus, dh sie ist zerbrechlich, instabil und nicht tragbar.

Schließlich denke ich an einen Abschnitt, in dem die Empfehlungen für das, was jetzt geschehen muss, aufgeführt sind. Dies sollten Änderungen an der Architektur / dem Design und eine Roadmap für Änderungen an der Software sein, damit Ihre Vision Wirklichkeit wird.

Ich denke, dies deckt (auf hohem Niveau) ab, was erfasst werden muss. Wie Sie dies in Bezug auf die Unterabschnitte des Dokuments oder der Bug-Tracking-Software tun, hängt von der Domäne ab, in der Sie arbeiten, von Ihren persönlichen Vorlieben, der Teamgröße, dem Budget, der Zeitskala usw.