Technical Debt Records – Dokumentation technischer Schulden

Zur Abwechslung geht es diesmal weder um Microcontroller noch um KI, sondern um Softwarearchitektur, genauer gesagt um technische Schulden und ihre Dokumentation. In der heutigen schnelllebigen Softwareentwicklung stehen Teams vor der Herausforderung, kontinuierlich neue Funktionen bereitzustellen und gleichzeitig die Codequalität zu erhalten. Dabei entstehen oft Kompromisse, die wir als Technical Debt (Technische Schulden) bezeichnen. Um diese systematisch zu dokumentieren und zu verwalten, lassen sich Technical Debt Records (TDRs) nutzen. Dieser Artikel erläutert die Bedeutung von TDRs und stellt ein Werkzeug vor, das die Erstellung von TDRs vereinfacht.

Anzeige

Was sind Technical Debt Records (TDRs)?

Softwarearchitektinnen und -architekten nutzen heutzutage ADRs (Architecture Design Records), wenn sie Architekturentscheidungen festhalten wollen. ADRs haben sich in einer Vielzahl von Projekten als Micro-Architekturdokumente etabliert. Sie unterliegen der Versionskontrolle und liegen damit in der Codebasis. Was für Architekturentscheidungen gilt, lässt sich auch für technische Schulden nutzen.

Ein Technical Debt Record (TDR) ist ein strukturiertes Dokument, das Details über technische Schulden in einem Softwareprojekt festhält. Technische Schulden entstehen, wenn Entwicklerinnen und Entwickler kurzfristige Lösungen wählen, die sich zwar schnell implementieren lassen, aber langfristig zu erhöhtem Wartungsaufwand, schlechterer Performance oder anderen Nachteilen führen. TDRs bieten eine klare Übersicht über bestehende technische Schulden, deren Auswirkungen und die Maßnahmen zu ihrer Behebung.

Motivation für TDRs

Technische Schulden können, wenn sie unkontrolliert bleiben, erhebliche negative Auswirkungen auf ein Projekt haben:

Durch die systematische Dokumentation mittels TDRs können Teams diese Schulden frühzeitig erkennen, priorisieren und gezielt angehen, bevor sie unkontrollierbar werden.

Vorteile von TDRs für Entwicklerinnen, Architekten und Tester

Es ist somit essenziell, technische Schulden zu dokumentieren. Technical Debt Records bieten hierbei verschiedene Vorteile für die Projektbeteiligten.

Für Entwickler:

Für Architekten:

Für Tester:

Damit die Beschreibung von Technical Debt Records nicht nur theoretisch bleibt, soll das konkrete Beispiel im folgenden Kasten zur Veranschaulichung dienen. Es geht um eine veraltete Authentifizierungsbibliothek. Hat das zugehörige TDR schon ein paar Stufen des Workflows durchlaufen, könnte es sich so präsentieren.

Das TDR-Template und seine Felder

Ein gut strukturiertes TDR-Template ist entscheidend für die effektive Dokumentation technischer Schulden. Ein Werkzeug (siehe weiter unten) generiert TDRs mit folgenden Feldern:

• Titel: Eine prägnante Bezeichnung der technischen Schuld.
• Autor: Die Person, die die Schuld identifiziert oder dokumentiert hat.
• Version: Die Version des Projekts oder der Komponente, in der die Schuld existiert.
• Datum: Das Datum der Identifikation oder Dokumentation der technischen Schuld.
• State: Der aktuelle Status der technischen Schuld (z.B. Identified, Analyzed, Approved, In Progress, Resolved, Closed, Rejected).
• Relations: Verweise auf andere verwandte ADRs oder TDRs, um Zusammenhänge zu verdeutlichen.
• Zusammenfassung: Eine kurze Übersicht über die technische Schuld und deren Bedeutung.
• Kontext: Detaillierte Hintergrundinformationen, warum die Schuld entstanden ist (z.B. Zeitdruck, veraltete Technologien).
• Auswirkungen:
  • Technische Auswirkungen: Wie die Schuld die Systemleistung, Skalierbarkeit oder Wartbarkeit beeinflusst.
  • Geschäftliche Auswirkungen: Die Auswirkungen auf Geschäftsprozesse, Kundenzufriedenheit oder Risikoebenen.
• Symptome: Beobachtbare Anzeichen, die auf die Präsenz der technischen Schuld hinweisen (z.B. häufige Bugs, langsame Performance).
• Schweregrad: Die Kritikalität der Schuld (Critical, High, Medium, Low).
• Potenzielle Risiken: Mögliche negative Folgen, wenn die Schuld nicht behoben wird (z.B. Sicherheitslücken, erhöhte Kosten).
• Vorgeschlagene Lösung: Empfohlene Maßnahmen zur Behebung der technischen Schuld.
• Kosten der Verzögerung: Die Konsequenzen, wenn die Behebung der Schuld verzögert wird.
• Aufwand zur Behebung: Geschätzter Aufwand in Zeit und Ressourcen, um die Schuld zu beheben.
• Abhängigkeiten: Andere Aufgaben, Komponenten oder externe Faktoren, die die Behebung der Schuld beeinflussen.
• Zusätzliche Hinweise: Weitere relevante Informationen oder Überlegungen zur Schuld.

Das sind auf den ersten Blick sehr viele Aspekte. Doch keine Sorge, die Dokumentation dieser Felder erfolgt inkrementell im Lebenszyklus der dokumentierten technischen Schuld. Den augenblicklichen Zustand und damit den Workflow eines TDR beschreibt das Feld state.

Rationale für das State-Feld

Das State-Feld spiegelt den Workflow wider, also wie Entwickler technische Schulden handhaben sollten. Es hilft dabei, den Fortschritt bei der Bearbeitung der Schuld zu verfolgen und sicherzustellen, dass keine Schulden unbeachtet bleiben. Die definierten Zustände sind:

• Identified: Die technische Schuld wurde erkannt.
• Analyzed: Die Auswirkungen und der Aufwand zur Behebung wurden bewertet.
• Approved: Die Behebung der Schuld wurde genehmigt.
• In Progress: Die Arbeit zur Behebung der Schuld ist im Gange.
• Resolved: Die technische Schuld wurde behoben.
• Closed: Der TDR wurde abgeschlossen und ist nicht mehr relevant.
• Rejected: Die Behebung der Schuld wurde abgelehnt.

Diese Zustände ermöglichen es Teams, den Status jeder technischen Schuld klar zu definieren und entsprechende Maßnahmen zu ergreifen.

Inkrementelle Anpassung der Felder je nach State

Beim ersten Identifizieren einer technischen Schuld können einige Felder noch leer bleiben:

• Initiale Identifikation (Identified):
  • Zu beschreiben: Titel, Autor, Version, Datum, State, Zusammenfassung, Kontext.
  • Leer: Auswirkungen, Symptome, Schweregrad, Potenzielle Risiken, Vorgeschlagene Lösung, Kosten der Verzögerung, Aufwand zur Behebung, Abhängigkeiten, Zusätzliche Hinweise.
• Analysephase (Analyzed):
  • Zu beschreiben: Alle Felder des Identified-Status plus Auswirkungen, Symptome, Schweregrad, Potenzielle Risiken.
• Genehmigungsphase (Approved):
  • Zu beschreiben: Alle bisherigen Felder plus Vorgeschlagene Lösung, Kosten der Verzögerung.
• Umsetzungsphase (In Progress):
  • Zu beschreiben: Alle bisherigen Felder plus Aufwand zur Behebung, Abhängigkeiten.
• Abschlussphase (Resolved & Closed):
  • Zu beschreiben: Alle Felder einschließlich Zusätzliche Hinweise.

Durch diese schrittweise Ergänzung bleibt die Dokumentation stets aktuell und reflektiert den Fortschritt bei der Behebung der technischen Schulden.

Ein Werkzeug zur Erstellung von TDRs

Die Dokumentation technischer Schulden würde dann an Akzeptanz verlieren, wenn die Dokumentation technischer Schulden sich als manuell und aufwendig erweist. In diesem Fall könnte es auch passieren, dass Entwickler Felder vergessen, umbenennen oder wichtige Felder ignorieren.

Der TDR-Generator ist ein Go-basiertes Werkzeug, das die Erstellung von Technical Debt Records in verschiedenen Formaten automatisiert. Es unterstützt Markdown, Plain ASCII, PDF und Excel und erleichtert somit die Integration in unterschiedliche Entwicklungs- und Dokumentationsprozesse.

Features des TDR-Generators

Werkzeugunterstützung für TDRs hat sich auch schon bei ADRs bewährt. So lassen sich Schablonen generieren, mit deren Hilfe Architektinnen und Architekten die technischen Schulden beschreiben. Dementsprechend weist der TDR-Generator folgende Vorteile auf:

Repository und Installation

Der TDR-Generator ist auf GitHub verfügbar. Sie können das Repository hier finden.

Zur Installation bedarf es folgender Schritte:

1. Klonen des Repositories: git clone [email protected]/ms1963/TechnicalDebtRecords.git
2. Initialisieren des Go-Moduls: go mod init technical_debt_generator
3. Installieren der Abhängigkeiten: go get github.com/phpdave11/gofpdf && go get github.com/xuri/excelize/v2
4. Kompilieren des Programmes: go build generate-td.go

Wer möchte, kann aber auch einfach make im Quellcodeverzeichnis aufrufen. Dadurch erfolgt die Kompilation automatisch über das mitgelieferte Makefile. Voraussetzung ist allerdings in jedem Fall die vorhergehende Installation des go-Compilers.

Nutzung des TDR-Generators

Das Programm lässt sich über die Kommandozeile mit verschiedenen Optionen ausführen.

Verfügbare Optionen:

• -format: Gibt das Ausgabeformat an. Mögliche Werte sind markdown, ascii, pdf, excel. Standard ist markdown.
• -output: (Optional) Gibt den Dateinamen für die Ausgabe an. Wenn nicht angegeben, wird ein Standardname verwendet.
• -empty: (Optional) Erstellt ein leeres TDR mit Platzhaltern, ohne nach Eingaben zu fragen.
• --help oder -h: Zeigt die Hilfsnachricht mit Nutzungshinweisen an.

Beispiele:

1. Generiere ein Markdown-Dokument: ./generate-td -format markdown
2. Generiere ein PDF-Dokument mit benutzerdefiniertem Dateinamen: ./generate-td -format pdf -output mein_td_record.pdf
3. Generiere ein leeres Excel-Dokument: ./generate-td -format excel -empty
4. Zeige eine Hilfemeldung an: ./generate-td --help

Integration in Versionskontrollsysteme

Um die Nachverfolgung und Zusammenarbeit zu erleichtern, sollten TDRs in ein Versionskontrollsystem wie Git oder SVN eingecheckt werden. Dies ermöglicht:

• Versionierung: Nachverfolgung von Änderungen und Historie der technischen Schulden.
• Zusammenarbeit: Gemeinsame Bearbeitung und Überprüfung von TDRs durch das Team.
• Zugänglichkeit: Einfache Integration in bestehende Entwicklungsprozesse und Pipelines.

Beispiel für Git:

1. Füge das TDR dem Repository hinzu: git add technical_debt_record.md
2. Bestätige die Änderung: git commit -m "Add TDR für veraltete Authentifizierungsbibliothek"
3. Speichere die Änderung: git push origin main

Durch die Einbindung von TDRs in das Versionskontrollsystem bleibt die Dokumentation stets aktuell und für alle Teammitglieder zugänglich.

Fazit

Technical Debt Records (TDRs) sind ein effektives Instrument zur Verwaltung technischer Schulden in Softwareprojekten. Sie bieten Transparenz, erleichtern die Priorisierung und unterstützen strategische Entscheidungen zur Verbesserung der Codequalität und Systemarchitektur. Der vorgestellte TDR-Generator vereinfacht die Erstellung dieser wichtigen Dokumente und integriert sich nahtlos in bestehende Entwicklungs- und Versionskontrollprozesse.

Indem Teams TDRs konsequent verwenden und in ihre Workflows integrieren, können sie die negativen Auswirkungen technischer Schulden minimieren und die langfristige Gesundheit und Wartbarkeit ihrer Softwareprojekte sicherstellen.

Wie erwähnt, finden Sie das beschriebene Werkzeug in einem GitHub-Repository.

(who)