Gibt es einen Standard für die Dokumentation der übergeordneten Architektur eines Programms?

Ich bin ein Amateurentwickler und alle meine bisherigen Programme waren einfach genug, um im Code dokumentiert zu werden. Beim Lesen des Codes war klar, was ich so und so tat (mein Standardtest bestand darin, den Code 6 Monate später zu betrachten und beim ersten Lesen alles zu verstehen - und ich habe eine kurze Speicherspanne).

Ich stehe jetzt vor einem Programm, das über meine Fähigkeiten hinauswächst, sich an die verschiedenen Wechselwirkungen zwischen ihnen zu erinnern

• der Code selbst
• die Indizes in der Datenbank
• die Interaktionen zwischen verschiedenen Modulen ("Worker" -Kerncode und "Library" -Module)

Meine aktuelle Dokumentation ist ein Whiteboard, auf dem ich alle Arten von Feldern und Pfeilen habe, die auf Code, Datenbankindizes, ausgeführte Aktionen, Statusänderungen usw. verweisen. Nur als Referenz ein Fragment des Chaos:

Meine Frage ist, ob es einen Standard oder einen benannten Satz von Best Practices (benannt in dem Sinne, dass dies ein Satz von Praktiken ist, die unter einem bestimmten Namen zusammengefasst wurden) für die Dokumentation komplexerer Produkte gibt.

Nach welchen Schlüsselwörtern sollte ich suchen (allgemeine Versuche, "Standards für die Softwarearchitektur zu dokumentieren" und ähnliche Variationen führten normalerweise zu Software für Workflows oder CAD-Systeme für Gebäudearchitekturen).

Ich gehe auch davon aus, dass es möglicherweise keine allgemeinen Best Practices für Beschreibungen auf hoher Ebene gibt und dass jeder seine eigene Philosophie entwickelt.

Es gibt keinen Standard, an den sich jeder hält. Softwareprojekte können sehr unterschiedlich sein (denken Sie an: helloworld.py im Vergleich zum Code im Space Shuttle).

Eine sehr häufige Methode ist die Verwendung des 4 + 1-Modells . Anstatt zu versuchen, alles in einen einzigen Dokumentstil zu packen, unterteilt diese Methode das Design in fünf Komponenten:

• Die Entwicklung Ansicht
• Die logische Ansicht
• Die physische Ansicht
• Die Prozessansicht
• Szenarien

Die verschiedenen Ansichten beschreiben das Produkt aus vier verschiedenen Perspektiven. In den Szenarien leben die Anwendungsfälle und beschreiben die Interaktion der anderen Ansichten.

Hinweis: Dies ist ein konzeptionelles Modell und nicht an ein bestimmtes Werkzeug gebunden.

Hier können Sie mehr lesen:

1. 4 + 1 Architekturansichtsmodell (Wikipedia)
2. Architectural Blueprints - Das 4 + 1-Ansichtsmodell der Softwarearchitektur (IEEE-Papier - pdf)

IMHO UML ist kein Tool, mit dem sich die Architektur realer Software gut dokumentieren lässt. Klassendiagramme sind nützlich, verwenden jedoch eine Abstraktionsebene, die für diesen Zweck häufig zu niedrig ist. Anwendungsfalldiagramme sind normalerweise zu "hochrangig" und übersehen bestimmte Aspekte. Andere UML-Diagrammtypen haben ähnliche Probleme (Um fair zu sein, können Paketdiagramme, Bereitstellungsdiagramme und Komponentendiagramme bestimmte architektonische Aspekte dokumentieren, aber ich persönlich fand sie nie sehr nützlich).

Wenn Sie nach einer funktionierenden, pragmatischen Methode suchen, um Architekturen auf hoher Ebene zu dokumentieren, empfehle ich Ihnen , sich mit Datenflussdiagrammen vertraut zu machen . Diese sind leicht zu verstehen und haben den Vorteil, dass sie auf verschiedene Abstraktionsebenen skaliert werden können. Ich fand sie am nützlichsten, um verschiedene Arten von Systemen zu dokumentieren. Schade, dass sie keinen Weg in UML gefunden haben, aber dennoch finden Sie viele Tools - sogar kostenlose wie Dia oder DrawIO -, um diese Diagramme zu erstellen.

Nebenbei bemerkt, warum benötigen Sie "Indizes in der Datenbank" in einer allgemeinen Dokumentation? Ich denke, sie sind ein Implementierungsdetail Ihres (relationalen?) Datenmodells, und ob Sie sie hinzufügen oder nicht, ist meiner Erfahrung nach eher eine Frage der Leistung und Optimierung.

Die Unified Modeling Language (UML) ist eine universelle Entwicklungsmodellierungssprache im Bereich der Softwareentwicklung, die eine Standardmethode zur Visualisierung des Systemdesigns bieten soll.

Ich denke, wir haben es früher besser gemacht. UML schien das Baby mit Badewasser hinauszuwerfen. Durch die Bereitstellung einer einheitlichen Modellierungssprache wurde die Unterscheidung zwischen Architektur und Implementierung aufgehoben. Oder wenn es nicht beabsichtigt war, schien dies zu bewirken.

Ich habe einige Monster-UML-Modelle gesehen und ehrlich gesagt tun sie nichts für mich, was der Code nicht kann, und machen es besser.