Was wissen Sie über dokumentengesteuerte Entwicklung?

Warum brauchen wir im Entwicklungsprozess überhaupt Dokumente?

Was ist mit der Aussage, dass der Code sich selbst dokumentiert ?

Betrachten wir das gängigste Szenario: Der Code des Systems (sei es ein Programm, Projekt oder Produkt) wird über einen langen Zeitraum geschrieben und das Team verändert sich während dieses Prozesses schrittweise, wobei mit dem Ausscheiden von Entwicklern bestimmte Kenntnisse über das System mitgenommen werden.

Was können wir in einem solchen Fall tun?

Die einfachste Antwort besteht darin , eine Spezifikation zu schreiben , die alle Implementierungsdetails erfasst, um sicherzustellen, dass das System die ursprünglichen Anforderungen erfüllt.

Es ist jedoch sehr schwierig, ein solches Dokument im Voraus zu schreiben, und während des Entwicklungsprozesses können sich einige Implementierungsdetails ändern (Anpassung an den Markt/neue Anforderungen an die Mechanik usw.). Was können wir uns also einfallen lassen, um den Busfaktor zu verbessern?

Versuchen wir, einem Ablauf zu folgen, der eine der möglichen Lösungen für das oben genannte Problem darstellen könnte.

Anforderungen und RFC

Zunächst müssen wir den ursprünglichen Entwurf auf Grundlage der Anforderungen der Stakeholder beschreiben und dokumentieren. Anschließend kann dieses Dokument mit anderen Teams geteilt und um Feedback gebeten werden: Bitten Sie um die Implementierung bestimmter Funktionen, kommentieren Sie den ursprünglichen Entwurf, korrigieren Sie eine bestimmte Schnittstelle usw. Ein solches Dokument kann als RFC bezeichnet werden.

RFC oder „Request for Comments“ ist ein Dokument, das an interessierte Parteien – darunter Entwickler, Architekten und andere Teams – verteilt wird, um Feedback, Kommentare und Vorschläge zu sammeln. Es ist weniger detailliert als eine Spezifikation und enthält nur das anfängliche Problem, die Aufgabe und den Lösungsbereich. Da es flexibler ist, können Änderungen am Design aktiv akzeptiert werden, was ein tiefes Verständnis der Aufgabe gewährleistet und eine qualitativ hochwertige und durchdachte Entscheidungsfindung ermöglicht.

Design-Engagement und ADR

Okay, wir haben die technischen Anforderungen definiert und die Anforderungen anderer Teams gesammelt . Was kommt als Nächstes?

In dieser Phase ist es notwendig, das Systemdesign und alle Hauptfunktionen, die es ausführen wird, fertigzustellen . Zu diesem Zweck schreiben wir einen ADR .

ADR oder „Architecture Decision Record“ ist ein Dokument, das wichtige Architekturentscheidungen aufzeichnet, die während des Softwareentwicklungsprozesses getroffen wurden. Jeder ADR beschreibt eine bestimmte Architekturentscheidung auf hoher Ebene, ihren Kontext, die in Betracht gezogenen Alternativen, die getroffene Entscheidung und die Motivation, diese spezifischen Details gegenüber anderen zu wählen.

Ein solches Dokument ermöglicht es jedem Teammitglied (und auch anderen Teams), die Prinzipien und Werte zu verstehen , die dem Design zugrunde liegen. Wenn ein neuer Entwickler Jahre später zum Team stößt und fragt: „Warum habt ihr das so gemacht?“, kann man ihm dieses Dokument zeigen, das alle seine Fragen beantwortet.

Spezifikation

Jetzt ist es an der Zeit, den Code und seine Spezifikationen zu schreiben. In dieser Phase arbeiten wir jede Funktion gründlich durch und fassen gleichzeitig alle Informationen und Implementierungsdetails in einem speziellen Dokument zusammen. Dieses Dokument sollte die aktuellen Low-Level-Anforderungen für das System widerspiegeln.

Ein wichtiger Punkt : Während des Software-Lebenszyklus kann sich eine solche Spezifikation erheblich ändern, und das ist in Ordnung. Es ist jedoch sehr wichtig, beim ursprünglichen Design und der ursprünglichen Architektur zu bleiben, um zu verhindern, dass die Codebasis unhandlich wird.

Versuchsplan

Warum wird das benötigt? Es ist wichtig, dass ein Testplan nicht auf der Grundlage von Code erstellt wird, der gemäß der Spezifikation geschrieben wurde (wir schreiben Code und testen diesen Code, damit er erfolgreich ist), sondern auf der Grundlage eines Entwurfs , der kritische Szenarien enthält, die korrekt verarbeitet werden müssen . Es ist auch sehr praktisch, dass Sie einen solchen Testplan zur Überprüfung an andere Teams senden können (für Integrationen oder einfach nur für zusätzliche Tests), wodurch klar wird, wie sich das System in verschiedenen Situationen verhält.

Was beinhaltet es?

• Alle möglichen Systembetriebsszenarien

  • Glücklicher Weg
  • Trauriger Weg
  • Fehlerbehandlung

• Alle möglichen Invarianten, die während des Systembetriebs eingehalten werden müssen

• Abnahmetests zur Überprüfung des Systemzustands beim Start (sollten die Umgebung berücksichtigen, z. B. Daten im Netzwerk)

  
  

Wir haben das Design fertiggestellt, den Code und die Spezifikation geschrieben und den Testplan zusammengestellt. Klingt schon ziemlich solide! Aber was könnten wir noch hinzufügen?

Einsatzplan

Ein solcher Plan könnte bis zu einem gewissen Grad erforderlich sein, um den Busfaktor zu verbessern und Bedingungen zu schaffen, unter denen jedes Teammitglied das System bereitstellen und seinen Status überprüfen kann.

Warum können wir nicht darauf verzichten? Wir können, aber in der realen Welt gibt es große Teams, in denen viele Leute für verschiedene Teile des Systems verantwortlich sind, und der Bereitstellungsprozess kann vollständig an DevOps delegiert werden. Was ist daran falsch, da wir Tests geschrieben, sie in CI eingefügt und auf Schwachstellen geprüft haben, brauchen wir dann noch etwas anderes? Vielleicht nicht, aber oft berücksichtigen Tests nicht den aktuellen Zustand des Systems und testen nicht ganz das, was wir möchten.

Was der Bereitstellungsplan enthalten könnte :

• Eine vollständige Beschreibung der Aktionen, die für die Bereitstellung durchgeführt werden müssen
• Bereitstellungsparameter:
  • Umgebungsvariablen
  • Ausgangszustand
  • Parameter für den Start
• Ein Plan für den Fall, dass bei einem Schritt etwas schief geht
• Ein Backup-Plan, wenn möglich
• Der notwendige Zustand, in den das System gebracht werden muss, falls eine Fortsetzung der Bereitstellung nicht möglich ist
• Nach der Bereitstellung auszuführende Aktionen
  • Andere Teams benachrichtigen
  • Aktivieren Sie bei Bedarf die erforderlichen Integrationen

Nichts Kompliziertes, oder? Ein solches Dokument für ein bestimmtes Update kann den Bus-Faktor erheblich verbessern und die Abhängigkeit von bestimmten Personen verhindern . Ist das nicht das, was wir wollen?

Abschluss

Im Softwareentwicklungsprozess ist es nicht nur wichtig, Code zu schreiben, sondern auch Dokumentation zu erstellen, die Verständnis und Konsistenz in allen Entwicklungsphasen gewährleistet. Die Dokumentation kann der Code selbst sein , aber die Erfahrung hat gezeigt, dass Dokumentation sehr wichtig ist, um die Qualität, Stabilität und zukünftige Skalierbarkeit des Systems aufrechtzuerhalten, insbesondere wenn sich das Team während der Entwicklung ändert und auch wenn sich das Projekt weiterentwickelt und an neue Anforderungen anpasst.

Zur Dokumentation gehören RFC (Request for Comments), ADR (Architecture Records), Spezifikationen , Testpläne , Bereitstellungspläne und mehr. Dies garantiert die Wissensspeicherung im Team , vereinfacht die Integration neuer Mitarbeiter in das Projekt und erhöht die allgemeine Zuverlässigkeit und Widerstandsfähigkeit des Systems gegenüber Änderungen .