Was macht Architekturdiagramm?
Ein Diagramm ist verstanden, wenn das, was es zeigt, an dem andockt, was der Leser bereits weiß. Ein Senior-Entwickler liest es für den Top-Level-Fluss und für die Nähte. Ein Block ist eine Blackbox: sein Entwurfsmuster, seine Verantwortlichkeit, sein Besitzer und sein Inneres verborgen. Was ein Block einem anderen über eine Naht hinweg anbietet, ist seine Schnittstelle: Operationen mit Parameter- und Rückgabetypen, Fehler, die Datentypen, die die Naht mit ihren Feldern überqueren, und ein Beispiel dessen, was genau überquert und wie es aussieht. Der Transport (REST, OPC UA, ein Prozessstart) ist ein Attribut einer Schnittstelle und ersetzt sie niemals.
Lies EXAMPLE.md vor dem Zeichnen: eine Änderung, vollständig, in beiden Formen.
Schritte
1. Die Worte des Lesers
Ein neuer Begriff dockt an nichts an. Sammle vor allem anderen die Worte, die der Leser bereits hat: aus seinen Nachrichten in diesem Gespräch, aus den Dokumenten, die er geschrieben hat (Projektanweisungen, Architekturseiten, Glossare, Nomenklaturtabellen), und aus jedem Modell, mit dem das Diagramm verglichen wird. Schreibe die Wortliste: das Ding, das Wort des Lesers dafür, das Wort jedes anderen Beteiligten, der das Diagramm lesen wird, der Name im Code und das Wort, das das Diagramm verwendet.
- Beschrifte jeden Block und jede Schnittstelle mit dem Wort des Lesers; der Codename steht daneben.
- Wo zwei Wörter kollidieren oder ein Wort für die falsche Sache verwendet wird, wähle eines aus, begründe dies in der Wortliste und nenne das andere einmal daneben.
- Prägen nichts. Eine Schnittstelle ohne Namen im Code wird nach ihren beiden Enden benannt,
Frontend -> Backend. - Beginne mit dem Bild, das der Leser bereits hat, seinem eigenen Diagramm mit seinen Ebenen und Namen, und platziere das Neue darin.
Fertig, wenn jede Beschriftung in einem Diagramm aus der Wortliste stammt und jeder Begriff, der für den Leser neu ist, im Glossar neben dem bekannten Wort steht, zu dem er gehört.
2. Fragen
Schreibe die Fragen des Lesers auf, eine pro Zeile. Sie wählen die Ansichten.
| Frage | Ansicht |
|---|---|
| Was sind die Teile, wofür ist jedes verantwortlich, wer besitzt es, wer ruft wen? | Bausteinansicht |
| Welche Schnittstelle verbindet zwei Teile, und was genau überquert sie? | die Schnittstelle, ihre Datentypen und ein Beispiel auf jeder Naht |
| Was passiert in welcher Reihenfolge in dem Szenario, das wichtig ist? | Laufzeitansicht: eine Sequenz |
| Wo läuft jeder Teil? | host: auf jedem Block; eine Bereitstellungsansicht, wenn Netzwerke oder Vertrauensgrenzen die Frage sind |
| Was bewirkt eine Änderung, oder wie unterscheiden sich zwei Entwürfe? | jeden Zustand in der gleichen Form, dann die Unterschiede |
Fertig, wenn jede Ansicht ihre Frage hat und die Frage als ihre Bildunterschrift darüber steht.
3. Katalog
Fülle vor dem Zeichnen vier Listen aus den Quellen.
- Blöcke: das Wort des Lesers und der Name im Code, Stereotyp, ein Satz Verantwortlichkeit, Besitzer, Host.
- Schnittstellen, eine pro Naht: Anbieter, Konsumenten, jede Operation als Signatur
name(param: Typ) -> Typ, Fehler, Transport. - Datentypen: jeder Typ, den eine Signatur benennt, mit seinen Feldern, Einheiten und Standardwerten.
- Beispiele, eines pro Schnittstelle: eine Nachricht, wie sie überquert, Aufruf und Antwort in ihrem realen Format: eine Befehlszeile mit ihrer Ausgabe, ein JSON-Body, eine Tabellenzeile. Nimm es von einem Lauf, einer Aufzeichnung, einer Testvorrichtung oder den Daten. Ein aus dem Code zusammengestelltes Beispiel sagt dies in seiner ersten Zeile.
Jeder Eintrag trägt seinen Ursprung: eine Code-Referenz pfad:zeile oder ein Tag (unten). Ein Zustand, den jemand anders gezeichnet hat, eine Modelldatei oder eine Skizze, wird so reproduziert, wie er ist und in seinen eigenen Worten; was er auslässt, wird mit [undefined] getaggt, und was du hinzufügst, geht in einen eigenen Zustand ein.
Fertig, wenn jeder Block seinen Satz hat, jede Naht eine Schnittstelle, deren Signaturen aus dem Code kopiert oder getaggt sind, jeder Typ in einer Signatur seine Felder, jede Schnittstelle ihr Beispiel und jeder Eintrag eine Referenz oder einen Tag hat.
4. Ebene
Die Blöcke eines Zustands sind gleichrangig: Einheiten, die eigenständig bereitgestellt, besessen oder ersetzt werden, fünf bis neun davon. Dateien, Funktionen und die Schritte innerhalb eines Blocks sind sein Inneres. Ein Zoom ist ein weiteres Diagramm eine Ebene tiefer, gezeichnet für den einen Block, um den es bei der Frage geht.
Fertig, wenn kein Block eines Zustands innerhalb eines anderen liegt und jeder Zoom die Frage nennt, die ihn rechtfertigt.
5. Form
- Chat-Form, bis zu 78 Spalten: die Bausteinansicht mit dem Namen der Schnittstelle und ihrer Hauptsignatur auf jeder Kante, dann der Katalog als Tabellen und die Beispiele als Codeblöcke. Für einen Zustand oder eine kleine Änderung.
- Leinwand-Form, eine statische HTML-Seite mit Textdiagrammen, so breit wie nötig: neben jeder Kante ihre Schnittstelle vollständig, das Beispiel und die Datentypen mit ihren Feldern. Für mehrere Zustände oder wenn mehr als drei Nähte vollständig gezeigt werden. Die Seite wird von einem Generator-Skript erstellt, das daneben liegt; die Chat-Antwort nennt die Datei, sagt in ein paar Sätzen, was der Vergleich zeigt, und listet die offenen Entscheidungen auf.
- C4-Form, das gleiche Modell gezeichnet mit LikeC4 auf einer Seite mit einem Tab pro Zustand, Kästchen zum Anklicken und zum Hineinzoomen. Die Textdiagramme sind sein Prototyp: kläre dort zuerst Wörter, Blöcke, Schnittstellen und Beispiele, dann rendere. Für ein Ergebnis, das andere Leute öffnen werden. Lies LIKEC4.md.
6. Zeichne
Zeichne mit den drei Dateien in diesem Ordner, damit Kästchen ausgerichtet sind und keine Zeile breiter ist als ihre Leinwand. Das Docstring jeder Datei ist seine Anleitung, und das Ausführen gibt eine Demo aus.
| Datei | Gibt |
|---|---|
grid.py | Grid (Kästchen mit Abteilen, Linien, Pfeilen), sequence (eine Laufzeitansicht), table |
canvas.py | glance (jeder Zustand in einer Zeile), overview (Zustände nebeneinander, eine Zeile pro Ebene), panel (ein Zustand: Blöcke, Schnittstellen mit Beispielen, Datentypen) |
page.py | html_page: die Seite um die Diagramme herum, mit den Farben und den Verknüpfungen zwischen IDs |
likec4/ | für die C4-Form: template.c4, build.sh, die Tab-Seite index.html mit tabs.js und clicktest.py |
Eine Seite geht vom Zehn-Sekunden-Bild bis ins Detail: auf einen Blick, die Wortliste, die Leseanleitung, die Übersicht, ein Panel pro Zustand, die Unterschiede pro Naht als Tabelle, die offenen Entscheidungen, Glossar, Quellen.
7. Prüfung
- Jedes Kästchen ist ein Block des Katalogs, jede Kante eine Schnittstelle, jedes Typ-Kästchen ein Datentyp; ein Eintrag, der aus einem Diagramm ausgelassen wird, ist absichtlich ausgelassen.
- Jede Code-Referenz ist auflösbar: die Datei existiert und die Zeile zeigt den Namen.
- Der gleiche Block steht an der gleichen Stelle in jedem Zustand. Ein Block, der in einem Zustand fehlt, ist dort ein gepunktetes Kästchen.
- Screenshots der gesamten Seite, Kachel für Kachel gelesen: Grenzen treffen zusammen, nichts ist abgeschnitten, Farben tragen ihre Bedeutung.
- Die Quellen nennen, was gelesen wurde, bei welchem Commit, welche Beispiele echt sind und was nicht gelesen wurde.
Zustände
Ein Zustand ist der Code, wie er ist, ein Ziel, das jemand gezeichnet hat, oder ein Vorschlag. Vergleiche Zustände nach Position: der gleiche Block in der gleichen Spalte von glance und der gleichen Zeile von overview, damit die Lücken zweier Zustände zeigen, wo sie sich ergänzen.
Eine Naht hat eine ID aus einem Buchstaben für ihren Zustand und einer Zahl, (I4). Eine Schnittstelle oder ein Datentyp, der an einer Naht definiert ist, wird überall sonst mit dieser ID referenziert; ihre Felder werden einmal geschrieben.
Die Unterschiede sind eine Tabelle mit einer Zeile pro Naht und einer Spalte pro Zustand. Die offenen Entscheidungen sind eine Tabelle: die Frage, die Optionen, wer entscheidet.
Tags und Stereotypen
| Tag | Bedeutung |
|---|---|
[code] | existiert im Code; die Referenz steht daneben |
ein Quell-Tag, z.B. [c4] | von einem Quellmodell angegeben; nenne das Tag in der Leseanleitung |
[proposed] | hier vorgeschlagen, existiert noch nirgendwo |
[new] [changed] [moved] | was eine Änderung bewirkt, wenn es nur Ist und Soll gibt |
[undefined] | der Zustand lässt es offen |
[?1] | eine offene Entscheidung, aufgelistet mit ihrer Nummer |
Stereotypen benennen das Entwurfsmuster, das ein Block spielt: <<ui>>, <<client>>, <<gateway>>, <<facade>>, <<service>>, <<port>>, <<adapter>>, <<repository>>, <<external>>. Verwende eines, wo der Code diese Rolle spielt; ein Block ohne Stereotyp ist besser als einer mit einem falschen. Ein Port ist eine Schnittstelle, die der Konsument besitzt und der Anbieter implementiert: <<port>> steht auf der Schnittstelle, <<adapter>> auf dem Block, der sie implementiert. Die eigenen Arten eines Quellmodells werden so zitiert, wie es sie schreibt.
Erklärungsmittel
Jedes dieser Mittel verdient seinen Platz, indem es etwas beantwortet, das der Leser sonst fragen müsste. Verwende sie sparsam.
- Leseanleitung: ein kleines Diagramm, das zeigt, wie ein Panel gelesen wird, und die Tags.
- Code-Referenzen: auf jeder Schnittstelle und jedem Datentyp, damit der Leser es nachschlagen kann.
- Kurze Texte: ein Absatz über einem Zustand, der die eine Sache sagt, die darin zu sehen ist; eine Notiz in einem Schnittstellen-Kästchen, wo der Leser nach dem Warum fragen würde.
- Glossar: die Begriffe, die die Wortliste nicht abdeckt, eine Zeile pro Begriff.
- Farbe: nur für die Tags, die IDs und ein oder zwei
key-Namen, die über alle Zustände hinweg gleich bleiben. Farbe markiert, was Zustände gemeinsam haben und wo sie sich unterscheiden; nichts anderes wird eingefärbt.
Prosa ist in der Sprache des Gesprächs. Namen aus Code und aus Quellmodellen werden wörtlich übernommen.