Was macht mein Sourcecode? – Dokumentation von Legacy Code

Lesezeit 4 min

Setzen Sie noch alten, undokumentierten Quellcode in ihrem embedded Projekt ein? Ist Ihnen das Knowhow zu Teilen ihrer Code Basis verloren gegangen? Benötigen Sie eine Dokumentation ihres bestehenden Quellcodes für eine anstehende Sicherheits-Zertifizierung?

Warum alten Quellcode nachdokumentieren?

Kommt Ihnen das bekannt vor? Der Quellcode ihres Embedded Software Projekts wurde schon vor vielen Jahren geschrieben. Kosten- und Zeitdruck damals wie heute führten dazu, dass der Quellcode nur unzureichend dokumentiert wurde.  Ingenieure, die den Aufbau und die Funktionalität des Quellcode noch kennen werden immer rarer. Die ursprünglichen Anforderungen sind unklar und nicht mehr allen beteiligten bekannt. Änderungen und Wartung werden immer teurer und riskanter. Dringend nötige Anpassungen werden hinausgezögert.

Aber das muss nicht das Ende sein. Ihr alter Quellcode ist nicht wertlos. Er hat seine eigenen Qualitäten. Alter Quellcode ist meist gut getestet (im Feld) und das Vertrauen in die Korrektheit und Zuverlässigkeit ist hoch. Er ist effizient, weil die verfügbare Rechenleistung bei der Erstellung oft noch sehr begrenzt war. Dazu kommt, dass eine Neuimplementation auch riskant sein kann, weil das Ergebnis meist schlechter getestet ist und weil Neuimplementationen z.B. zu Feature Creep und dem 2nd System Effekt neigen.

Falls Sie sogar planen ihren bestehenden Quellcode für ein functional Safety Projekt wiederzuverwenden, so sind Sie sowieso gezwungen ihren Quellcode zu dokumentieren und die Anforderungen genau abzuklären. Ähnliches gilt mittlerweile auch, wenn Ihnen Informationssicherheit ein Anliegen ist.

Was gehört in die Software-Dokumentation?

Quellcode kann nachdokumentiert werden und wird dadurch wieder wartbar und fit für die Zukunft. Für funktionale Sicherheit  sind die Anforderungen an eine Software-Dokumentation relativ klar spezifiziert, aber auch sehr weitreichend. Zusätzlich zur Dokumentation müssen sie z.B. auch eine Software Safety Analyse (Software-FMEA) durchführen. Dazu benötigen Sie genaue Kenntnisse der Software-Architektur und der Software-Funktionalität.  Aber auch für nicht sicherheitsrelevante Projekte können einige der folgenden Dokumentationselemente nützlich sein:

• Funktionelle und nicht-funktionelle Anforderungen inkl. Nachverfolgbarkeit (Traceability)
  • Welches Verhalten wird von der Software garantiert?
• Struktureller Aufbau:
  • Die statische Sicht auf die Software, Klassendiagramme, Abhängigkeiten, Packages
• Zustandsdiagramme, Sequenzdiagramme:
  • Die dynamische Sicht auf die Software
• Kontrollflussdiagramme:
  • Wie werden die Entscheidungen getroffen
• Datenflussdiagramme:
  • Von wo nach wo fliessen die Datenelemente
  • Welche Informationen werden wo im Code benötigt?
• Data Dictionary:
  • Welche Datenelemente existieren, und wie werden Sie dargestellt.

Dazu kommt je nach Projekt noch Dokumentation auf tieferem Abstraktionsgrad, z.B.:

• Kommentare im Quellcode
• Nachverfolgbarkeit im Quellcode
  • Wieso existiert die Funktion?
• Data Dictionary:
  • Detaillierte Funktionsparameter

Nicht für alle Projekte sind alle Dokumentationselemente zwingend nötig und wichtig. Hier gilt es genau abzuwägen, wo sich eine Investition in die Dokumentation lohnt.

Kann man die Software-Dokumentation automatisieren?

Einige der oben erwähnten Dokumentationselemente lassen sich sehr gut durch (teil-) automatisierte Prozesse (Skripte, Einsatz von CLANG/ LLVM) aus dem existierenden Quellcode erstellen. Dazu gehören insbesondere der strukturelle Aufbau der Software und eventuell auch das Data Dictionary.

Auch das nachträgliche Dokumentieren des dynamischen Verhaltens, z.B. das Erstellen von Zustandsdiagrammen, lässt sich teilweise automatisieren. Bedingung ist allerdings, dass die Struktur der Implementation geradlinig und konsistent ist. Hier ist es von Vorteil, wenn bei der ursprünglichen Implementierung konsequent auf den Einsatz eines Frameworks und auf Coding Guidelines geachtet wurde. Falls dies nicht zutrifft, hilft nur eine aufwändige manuelle Analyse des gesamten Quellcodes.

Der Kontrollfluss und der Datenfluss in einem alternden embedded Software-Projekt ist leider aufgrund von Optimierungsmassnahmen häufig sehr undurchsichtig und durch automatisierte Prozesse nicht mehr zu extrahieren. Eine manuelle Analyse durch einen erfahrenen embedded Software-Ingenieur ermöglicht es trotzdem, wieder einen guten Überblick zu gewinnen.

Das Gleiche gilt auch für Dokumentationselemente, die Erfahrung, Kreativität und einen Abgleich mit allen betroffenen Personen benötigen. Dazu gehören z.B. die funktionellen und nicht-funktionellen Anforderungen sowie die Erstellung der Nachverfolgbarkeit der Anforderungen (bei Bedarf bis hinunter in den Quellcode). Das benötigte Wissen, um die damaligen und heutigen Anforderungen zusammenzutragen, ist meist nur noch in den Köpfen der verbliebenen Ingenieure und Produktmanagern vorhanden. Dieses Wissen kann z.B. mit gezielten Interviews wieder nutzbar gemacht werden.

Wie komme ich zu einer sinnvollen und nützlichen Software- Dokumentation?

Das nachträgliche Erstellen einer Software Dokumentation ist ein zeitraubender und teurer Prozess. Es lohnt sich deshalb, genau zu planen, welche Dokumentationselemente in welchem Detaillierungsgrad Sie benötigen, um Ihre Ziele effizient zu erreichen.

Das Thema Testen und die Erstellung von Testlisten wurde in diesem Blog ausgeklammert. Effizientes Testen beruht aber immer auf einer gut dokumentierten Architektur und vollständigen Anforderungen.  Es ist ein ebenso relevanter Teil der qualitativ hochwertigen Software-Entwicklung wie die Dokumentation.

Wir verfügen über umfangreiches Know-How im Bereich Dokumentation und Zertifizierung und können Sie kompetent beraten. Wenn Sie Fragen haben zur Nachdokumentation von bestehender Software, zur Safety-Zertifizierung oder zum Testen von Embedded-Software, nutzen Sie unsere SolceptClinic. Und das Beste ist: diese erste time-boxed Konsultation von 30 Minuten kostet Sie nichts.

Daniel Megnet

Haben Sie zusätzliche Fragen? Haben Sie eine andere Meinung? Wenn ja, mailen Sie mir oder kommentieren Sie Ihre Gedanken unten!

Möchten Sie von unserem Wissen profitieren? Besuchen Sie unsere Kontaktseite!