„Architecture.md (2021)“ – technische Spezifikation

Empfehlung zum Verfassen von ARCHITECTURE.md

• Open-Source-Projekt-Maintainern wird nachdrücklich empfohlen, neben README und CONTRIBUTING ein ARCHITECTURE-Dokument hinzuzufügen.
• Dieses Dokument beschreibt die High-Level-Architektur des Projekts und sollte kurz gehalten werden, da es von wiederkehrenden Beitragenden gelesen werden soll.
• Ein ARCHITECTURE-Dokument sollte nur Inhalte enthalten, die sich nicht häufig ändern; statt zu versuchen, es mit dem Code zu synchronisieren, ist es besser, es einige Male pro Jahr zu überprüfen.

Zweck und Bedeutung des Dokuments

• Das Wissen über die physische Architektur eines Projekts ist der größte Unterschied zwischen gewöhnlichen Beitragenden und Kernentwicklern.
• Wenn man mit einem Projekt nicht vertraut ist, dauert das Schreiben eines Patches doppelt so lange, und herauszufinden, an welcher Stelle der Code geändert werden muss, kostet zehnmal so viel Zeit.
• Eine ARCHITECTURE-Datei ist ein wirksamer Weg, diese Lücke zu schließen, und bietet zugleich die Gelegenheit, über die Struktur des Projekts zu reflektieren.

Aufbau des Dokuments

• Es sollte mit einem Überblick aus einer neuen Perspektive auf das Problem beginnen und dann eine detaillierte Code-Map liefern, die die Beziehungen zwischen den Modulen erklärt.
• Wichtige Dateien, Module und Typen sollten genannt werden; statt direkt zu verlinken, sollte dazu ermutigt werden, nach Namen zu suchen, damit kein Pflegeaufwand entsteht.
• Architektonische Invarianten sollten ausdrücklich benannt und Grenzen zwischen den Schichten hervorgehoben werden.

Architektonische Invarianten und Grenzen

• Wichtige Invarianten werden oft durch die Abwesenheit von etwas ausgedrückt, und das lässt sich allein durch das Lesen des Codes nur schwer erkennen.
• Grenzen zwischen Schichten oder Systemen enthalten implizit Informationen über die Implementierung des Systems und schränken alle möglichen Implementierungen ein.

Querschnittsthemen

• Nach Fertigstellung der Code-Map sollte ein eigener Abschnitt zu Querschnittsthemen hinzugefügt werden.
• Ein gutes Beispiel für ein ARCHITECTURE-Dokument ist die architecture.md von rust-analyzer.

GN⁺-Meinung:

• Ein ARCHITECTURE-Dokument hilft beim Verständnis des Projekts und spielt eine wichtige Rolle dabei, dass neue Beitragende sich schnell in die Codebasis einarbeiten.
• Dieses Dokument macht die Struktur des Projekts klarer und hebt wichtige Architekturprinzipien und Grenzen hervor, damit Entwickler das System besser verstehen.
• Die Einführung von ARCHITECTURE-Dokumenten in der Open-Source-Community kann zu nachhaltigem Wachstum und besserer Wartbarkeit von Projekten beitragen und ist ein sehr nützlicher und interessanter Ansatz für Entwickler.

[GN⁺]

Hacker-News-Kommentare

• Wenn du ein Open-Source-Projekt pflegst und der Codeumfang zwischen 10k und 200k Zeilen liegt, empfehle ich dringend, ein ARCHITECTURE-Dokument hinzuzufügen.

  • Die Idee ist gut, aber ich denke, man kann die Architektur unabhängig von der Größe des Repositories auch in die README aufnehmen. Ich platziere zum Beispiel bewusst ein Mermaid-Sequenzdiagramm in der Haupt-README, damit alle Nutzer den Workflow verstehen können.

• Dieser Ansatz ist großartig als wartungsarmes Modell für Open-Source-Projekte mit vielen ad hoc beitragenden Personen. Bei Projekten mit dedizierten Engineers sollte man ADRs in Betracht ziehen. Das erfordert zwar mehr Pflege, ist aber sehr hilfreich bei einer Neugestaltung, weil das "Warum" und die "in Betracht gezogenen Alternativen" festgehalten werden.

• Vor ein paar Jahren habe ich bei einem meiner größeren Nebenprojekte etwas Ähnliches ausprobiert:

  • Am Anfang jeder Datei gab es einen Link-Baum zu anderen ARCHITECTURE.md-Dateien.

• Jede IDE zeigt links die Ordnerstruktur eines Projekts als normalen Verzeichnisbaum an. Gibt es eine IDE, die es unterstützt, ein Projekt über einen Abhängigkeitsgraphen zu erkunden?

• Man sollte vorsichtig sein, das, was der Autor hier geschrieben hat, auf allgemeine Softwareprojekte zu verallgemeinern. Bei großen Open-Source-Projekten mit vielen Beitragenden und wenig Kontext pro Person hat es Wert, solche Dokumente zu pflegen. Aber in kleinen Arbeitsprojekten sind alle von Entwicklern geschriebenen Dokumente, die ich gesehen habe, irgendwann ungepflegt geworden.

• Je kürzer ein Dokument ist, desto geringer ist die Wahrscheinlichkeit, dass es durch künftige Änderungen ungültig wird. Das ist die wichtigste Regel für ein ARCHITECTURE-Dokument — beschreibe nur Dinge, die sich wahrscheinlich nicht oft ändern. Versuche nicht, es mit dem Code zu synchronisieren.

  • Schnittstellen ändern sich seltener und [sind schwieriger!] (Parnas, die Kriterien, die verwendet werden, um ein System in Module zu zerlegen).

• In jedem Projekt zeige ich beim Onboarding ein Architekturdiagramm und eine kurze Beschreibung seiner Komponenten.

  • Inzwischen überrascht es mich, wie selten das in Open Source ist.

• Das ist eine sehr nützliche Praxis. In vielen Projekten gibt es ein paar zentrale Dateien (oder Pakete/Module/etc.), in denen die meisten Änderungen stattfinden. Wenn man neuen Beitragenden (oder Beitragenden, die nach längerer Zeit zurückkehren) hilft, diese schnell zu verstehen, kann das die Anlaufzeit für die Mitarbeit am Projekt massiv verkürzen.

• Ich war immer ein Fan solcher kleinen dokument- bzw. codebasierten Diagrammstandards:

  • README-getriebene Entwicklung
  • ARCHITECTURE.md
  • ADRs
  • arc42
  • C4
  • usw.
  • Inzwischen lege ich einen Obsidian-Vault in den /docs-Ordner eines Git-Repositories.
  • Statt den Standard anderer Leute zu verwenden, organisiere und refaktoriere ich die Dokumentation so, wie ich meine persönlichen Notizen in Obsidian verwalte.
  • Ich habe versucht, eine gemeinsame Markdown-Teilmenge zu verwenden, die sowohl in GitHub (GFM) als auch in Obsidian funktioniert, habe das aber letztlich aufgegeben und nutze nun Obsidians Markdown und seine speziellen Funktionen.
  • Obsidian hat Mermaid und LaTeX eingebaut und es gibt ein Plugin für PlantUML.
  • Für visuelle Bilder/Diagramme sind Canvas, DrawIO und Excalidraw integriert.

• Damals diskutiert:

  • Architecture.md - Feb 2021 (153 Kommentare)