Kaffeepause Nr. 20. Was ist Legacy-Code und wie wird damit gearbeitet? Tools, die das Schreiben technischer Dokumentation erleichtern

Was ist Legacy-Code und wie wird damit gearbeitet?

Quelle: Dou Früher und später wird ein Programmierer wahrscheinlich auf veralteten Code stoßen. Um die Konsequenzen dieser Bekanntschaft zu mildern, habe ich einige praktische Tipps und Beispiele aus meiner eigenen Erfahrung ausgewählt – insbesondere aus der Arbeit mit einem alten Java-System.

Legacy-Funktionen

Legacy ist der Code eines anderen, der oft so schrecklich ist, dass im Allgemeinen nicht klar ist, wie man damit arbeitet. Und wenn Sie mit einem Legacy-System arbeiten müssen, stoßen Sie neben dem alten Code auch auf Folgendes:

• mit veralteter Technologie;
• heterogene Architektur;
• Fehlen oder sogar völliges Fehlen einer Dokumentation.

Tatsächlich ist Legacy-Code nicht so beängstigend, und hier ist der Grund: Wenn das System all diese zehn Jahre gelebt hat und immer noch funktioniert, dann hat es einen gewissen Nutzen. Vielleicht verdient es gutes Geld (im Gegensatz zu Ihrem letzten Startup). Darüber hinaus ist dieser Code relativ zuverlässig, wenn er so lange in der Produktion überleben konnte. Daher müssen Änderungen daran mit Vorsicht vorgenommen werden. Zunächst müssen Sie zwei Dinge verstehen:

1. Wir können ein System, das Millionen verdient oder auf das täglich Tausende von Menschen zugreifen, nicht missachten. Egal wie schlecht er geschrieben war, dieser widerliche Code überlebte bis zur Produktion und funktioniert rund um die Uhr.

2. Da dieses System echtes Geld bringt, ist die Arbeit damit mit großer Verantwortung verbunden. Dies ist kein Startup, sondern etwas, mit dem Benutzer morgen arbeiten werden. Dies impliziert auch sehr hohe Fehlerkosten, und hier kommt es nicht auf die Behauptungen des Kunden an, sondern auf die tatsächliche Sachlage.

Reverse Engineering

Um erfolgreich mit Legacy-Code arbeiten zu können, müssen Sie Reverse-Engineering-Techniken verwenden. Zunächst müssen Sie den Code sorgfältig lesen, um genau zu verstehen, wie er funktioniert. Dies ist zwingend erforderlich, da wir höchstwahrscheinlich keine Dokumentation haben werden. Wenn wir den Gedankengang des Autors nicht verstehen, werden wir Änderungen mit unvorhersehbaren Folgen vornehmen. Um sich davor zu schützen, müssen Sie sich auch mit dem nebenstehenden Code befassen. Und sich gleichzeitig nicht nur in der Breite, sondern auch in der Tiefe bewegen. Wo wird die Methode mit dem Fehler aufgerufen? Woher kommt der Code, der es aufruft? In einem Legacy-Projekt werden „Aufrufhierarchie“ und „Typhierarchie“ häufiger als alles andere verwendet. Sie werden viel Zeit mit dem Debugger verbringen müssen: erstens, um Fehler zu finden und zweitens, um zu verstehen, wie alles funktioniert. Was die Dokumentation betrifft, wäre es keine schlechte Idee, auf die Industriearchäologie zurückzugreifen. Es kann sehr nützlich sein, irgendwo alte Dokumentation auszugraben und mit denen zu sprechen, die sich daran erinnern, wie der von Ihnen geerbte Code geschrieben wurde. Mit diesen Techniken werden Sie früher oder später beginnen, den Code mehr oder weniger zu verstehen. Damit Ihre Bemühungen jedoch nicht umsonst sind, müssen Sie die Ergebnisse Ihrer Recherche unverzüglich dokumentieren. Dazu empfehle ich das Zeichnen von Blockdiagrammen oder Sequenzdiagrammen. Natürlich werden Sie faul sein, aber Sie müssen dies auf jeden Fall tun, sonst werden Sie sich in sechs Monaten ohne Dokumentation durch diesen Code wühlen, als wäre es das erste Mal.

Schreiben Sie den Code nicht neu

Das Wichtigste im Entwicklungsprozess ist, dass Sie pünktlich sind und nicht versuchen, den gesamten Code von Grund auf neu zu schreiben. Schätzen Sie, wie viele Mannjahre dafür erforderlich sein werden. Es ist unwahrscheinlich, dass der Kunde so viel Geld ausgeben möchte, um etwas zu überarbeiten, das bereits funktioniert. Dies gilt nicht nur für das System als Ganzes, sondern auch für jeden Teil davon. Natürlich kann es sein, dass Sie eine Woche Zeit haben, um alles herauszufinden, und eine weitere Woche, um etwas zu reparieren. Es ist jedoch unwahrscheinlich, dass Sie zwei Monate Zeit haben, um einen Teil des Systems erneut zu schreiben. Implementieren Sie die neue Funktionalität stattdessen im gleichen Stil wie den Rest des Codes. Mit anderen Worten: Wenn der Code alt ist, sollten Sie sich nicht dazu verleiten lassen, neue schöne Technologien zu verwenden: Solcher Code wird dann sehr schwer zu lesen sein. Sie könnten beispielsweise auf eine Situation wie bei uns stoßen: Ein Teil des Systems ist in Spring MVC geschrieben und ein Teil ist in reinen Servlets geschrieben. Und wenn in einem in Servlets geschriebenen Teil noch etwas hinzugefügt werden muss, dann fügen wir es auf die gleiche Weise hinzu – in Servlets.

Respektieren Sie Geschäftsinteressen

Es muss daran erinnert werden, dass alle Aufgaben in erster Linie vom Wert für das Unternehmen bestimmt werden. Wenn Sie dem Kunden die Notwendigkeit bestimmter Änderungen aus betriebswirtschaftlicher Sicht nicht nachweisen, werden diese Änderungen nicht stattfinden. Und um den Kunden zu überzeugen, müssen Sie versuchen, an seiner Stelle zu stehen und seine Interessen zu verstehen. Insbesondere wenn Sie ein Refactoring durchführen möchten, nur weil der Code schwer lesbar ist, dürfen Sie dies nicht tun und müssen damit leben. Wenn Sie es wirklich nicht ertragen können, können Sie den Code in aller Stille und nach und nach neu organisieren und die Arbeit auf Geschäftstickets verteilen. Oder überzeugen Sie den Kunden davon, dass sich dadurch beispielsweise die Zeit zur Fehlersuche verkürzt und damit letztlich auch die Kosten sinken.

Prüfen

Es ist klar, dass Tests in jedem Projekt notwendig sind. Bei der Arbeit mit Legacy-Systemen muss jedoch besonderes Augenmerk auf das Testen gelegt werden, auch weil die Auswirkungen vorgenommener Änderungen nicht immer vorhersehbar sind. Sie benötigen mindestens so viele Tester wie Entwickler, ansonsten sollten Sie unglaublich gut in der Automatisierung sein. In unserem Projekt bestand das Testen aus den folgenden Phasen:

1. Verifizierung, wenn die implementierte Funktionalität eines Features in einem separaten Zweig überprüft wird.
2. Stabilisierung, wenn ein Release-Zweig geprüft wird, in dem alle Features zusammengeführt werden.
3. Zertifizierung, wenn dasselbe noch einmal in leicht unterschiedlichen Testfällen in einer Zertifizierungsumgebung ausgeführt wird, die hinsichtlich der Hardwareeigenschaften und -konfiguration möglichst nah an der Produktion ist.

Und erst wenn wir alle diese drei Phasen durchlaufen haben, können wir eine Veröffentlichung vornehmen. Jemand denkt wahrscheinlich, dass die Zertifizierung eine zusätzliche Phase ist, da in der Stabilisierungsphase bereits alles geklärt ist, aber unsere Erfahrung zeigt, dass dies nicht der Fall ist: Manchmal passiert bei einem Regressionstest, der für die zweite Runde auf einer anderen Maschine durchgeführt wird, irgendwie etwas es wird herauskommen.

Formalisieren Sie DevOps und Release

Das Freigabeverfahren könnte beispielsweise wie folgt aussehen. Wenn die Entwicklung abgeschlossen ist und zwei oder drei Testphasen abgeschlossen sind, schreiben wir 36 Stunden vor dem voraussichtlichen Release-Zeitpunkt eine E-Mail an das DevOps-Team. Danach rufen wir das Entwicklerteam an und besprechen alle Änderungen an den Umgebungen (wir informieren sie über alle Änderungen in der Datenbank und Konfiguration). Für jede Änderung haben wir ein Dokument (ein Ticket in Jira). Dann, während der Veröffentlichung, kommen alle Beteiligten zusammen und jeder sagt, was er jetzt macht: „Wir haben die Datenbank hochgeladen“, „Wir haben diese und jene Server neu gestartet“, „Wir haben Regressionstests in der Produktionsumgebung durchgeführt.“ ” Wenn etwas schief geht, wird das Release-Rollback-Verfahren gestartet, das im Original-Release-Dokument genau beschrieben ist – ohne ein solches Dokument werden wir definitiv etwas vergessen oder verwirrt sein.

Kontrollieren Sie die Codequalität

Und schließlich ist die Codeüberprüfung eine Praxis, die aus irgendeinem Grund nicht in allen Projekten angewendet wird. Es ist großartig, wenn jeder Code von mehr als einer Person überprüft wird. Selbst in einem sehr starken Team werden während des Code-Review-Prozesses immer einige Fehler entdeckt, und wenn sich mehrere Personen damit befassen, erhöht sich die Anzahl der identifizierten Fehler. Außerdem findet der dritte oder vierte Rezensent manchmal das Schlimmste.

Tools, die das Schreiben technischer Dokumentation erleichtern

Quelle: Dzone Die meisten Programmierer schreiben nicht gerne technische Dokumentation. Der Psychologieexperte Gerald Weinberg nannte Dokumentation sogar „das Rizinusöl der Programmierung“: Entwickler lieben es, sie zu lesen, aber sie hassen es einfach, sie selbst zu schreiben. Ein Mangel an Anleitung oder eine leere Roadmap führt zu einem Mangel an Informationen darüber, wie verschiedene Teile der Software funktionieren. Dies verschlechtert letztendlich die Erfahrung der Endbenutzer mit dem Code, da sie sich mangels Dokumentation nicht auf die Genauigkeit und Nützlichkeit des Produkts verlassen können. Um es Programmierern zu erleichtern, sich das Schreiben von Dokumentationen zur Gewohnheit zu machen, empfehle ich, auf vier hervorragende Tools zu achten, die mittlerweile fast jedem zur Verfügung stehen.

GitHub-Seiten

Es gibt heute wahrscheinlich keinen einzigen Entwickler, der nicht Erfahrung mit der Arbeit auf GitHub hat. Es ist auch ein großartiger Ort für Programmierer, die einen Ort zum Speichern von Dokumentation benötigen. Viele Leute verwenden eine Standard-Readme-Datei in ihrer Codebasis, um dem Benutzer eine einfache Anleitung zur Verfügung zu stellen, aber dies ist nicht die einzige Möglichkeit, Dokumentation auf GitHub zu erstellen. Mit GitHub Pages erhalten Sie mehr als nur Hosting für die Seiten Ihres Projekts, einschließlich Dokumentation und Tutorials. Sie erhalten die Möglichkeit, direkt mit allen GitHub-Repositorys zu interagieren, sodass Entwickler die Dokumentation auf die gleiche Weise aktualisieren können, wie sie ihren Code aktualisieren. Darüber hinaus können Sie hier Jekyll verwenden – es hilft Ihnen, Ihr Markup in einfachen Text oder in vollwertige Webseiten umzuwandeln.

Lesen Sie die Dokumente

Wie der Name schon sagt, bietet Read the Docs Entwicklern eine Plattform zum Speichern und Lesen von Dokumentationen. Der Dienst funktioniert ähnlich wie GitHub Pages: Programmierer können Änderungen an der Dokumentation über ihre bevorzugten Versionskontrollsysteme vornehmen, darunter Git, Bazaar, Mercurial und andere. Automatische Versionierung und Seitenerstellung werden ebenfalls unterstützt. Das Beste an Read Docs ist seine Flexibilität. Es unterstützt Webhooks, sodass Sie einen Großteil des Dokumentenerstellungsprozesses automatisieren können. Dies ist eine enorme Zeitersparnis bei einer Aufgabe, mit der die meisten Programmierer nichts zu tun haben möchten. Darüber hinaus steht alles, was auf der Plattform gehostet wird, der breiten Öffentlichkeit in verschiedenen Formaten zur Verfügung, darunter PDF, Single-Page-HTML und sogar E-Book-Format. Der Service übernimmt einen wesentlichen Teil der Routinearbeiten zur Aktualität der Dokumentation.

Tetra

Tettra ist nicht nur eine Plattform zum Speichern von Softwaredokumentationen, sondern eine vollständige Wissensdatenbank. Dies funktioniert besonders gut, wenn an einem Projekt eine große Gruppe von Programmierern beteiligt ist, die an verschiedenen Softwareteilen arbeiten. Mit Tettra können Antworten auf häufig gestellte Fragen dokumentiert werden.

Bienenhaus

Was Apiary für Entwickler so nützlich macht, ist die Tatsache, dass es bei der API-Dokumentation hervorragende Arbeit leistet. Die Plattform ermöglicht es Benutzern, ihre Dokumentation in Markdown zu schreiben , einschließlich simulierter API-Aufrufe. Mit Apiary können Sie auch API-Elemente testen und Prototypen erstellen. Mit anderen Worten: Es handelt sich um ein Dokumentationstool und eine Testplattform an einem Ort.