© Abscent/Shutterstock.com
Große und komplexe Anwendungen mit Angular umsetzen

Angular-Anwendungen optimal dokumentieren


An großen Softwareprojekten arbeiten in der Regel viele Entwickler in mehreren Teams über einen längeren Zeitraum. Daraus ergeben sich einige Herausforderungen. So wird es immer wieder vorkommen, dass bestimmte Eigenschaften oder auch Eigenheiten einer Softwarelösung nicht allen Entwicklern in jeder Detailstufe bekannt sind. Auch können Entwickler zwischenzeitlich ausfallen oder neue Entwickler in ein Team aufgenommen werden, sei es durch Projektwechsel oder krankheitsbedingte Ausfälle. In all diesen Fällen ist es notwendig, dass Entwickler sich schnell und effizient in die bestehende Software einarbeiten können.

Auch wenn ein mit dem Projekt vertrauter Entwickler nach längerer Abwesenheitszeit wieder in ein Softwareprojekt einsteigt, wird er eine gewisse Zeit benötigen, um sich erneut in die Software einzufinden. Um andere Entwickler und auch sich selbst besser bei dieser (Wieder-)Einfindungsphase zu unterstützen, sollte daher jeder Entwickler parallel zur Software eine ausführliche Dokumentation anlegen und auch pflegen.

Sorgfältig dokumentieren

Eine aussagekräftige Dokumentation zeichnet sich in erster Linie dadurch aus, dass sie leicht auffindbar ist. Sie muss außerdem aktuell sein und zur jeweiligen Version der Software passen – schlimmer als keine Dokumentation zu besitzen, ist es, nur eine veraltete Dokumentation zur Verfügung zu haben. Der Entwicklungsprozess sollte daher neben dem Quellcode auch die zu erzeugende Dokumentation berücksichtigen. Das bedeutet einerseits, dass immer eine Liveversion der Dokumentation zur Entwicklungszeit in Form von Doc-Kommentaren zur Verfügung stehen sollte. So kann die Dokumentation von IDEs ausgewertet werden, um sie dem Entwickler zu gegebener Zeit anzuzeigen. Andererseits sollte eine Version der Dokumentation – sinnvollerweise die, die dem momentan in Produktion befindlichen Software­stand entspricht – an zentraler Stelle, zum Beispiel in Form einer Webseite, bereitgestellt werden. In agilen Entwicklungsprozessen erweist es sich darüber hinaus als sinnvoll, die vollständige Dokumentation der Software in die „Definition of Done“ für einen Sprint aufzunehmen und gleichzeitig festzulegen, was „vollständig“ bedeutet.

Softwaredokumentation lässt sich auf unterschiedliche Weise erzeugen, beispielsweise mithilfe von Wiki-Einträgen oder anderen externen Werkzeugen, oder als automatisch aus dem Code generiertes Dokument. Um die optimale Art von Dokumentation für ein Projekt zu bestimmen, sollte der Entwickler die gegebenen Rahmenbedingungen berücksichtigen.

In großen, agil vorgehenden Teams beispielsweise ändert sich der Code meist parallel auf verschiedenen Entwicklungszweigen. Entsprechend schnell und nebenläufig muss die Dokumentation hier aktualisierbar sein und den Zustand auf den verschiedenen Zweigen widerspiegeln. Mit Wiki-Systemen lässt sich das zum Beispiel nur schwer abbilden. Auch mit externen Tools erstellte Dokumente, etwa Word-Dokumente, schaffen hier keine Abhilfe. Allein das Zusammenführen von Dokumenten aus verschiedenen Entwicklungsständen oder Entwicklungszweigen ist in der Regel nur aufwendig von Hand umsetzbar, nicht jedoch automatisch. Hier bietet sich daher eine Dokumentation nah am Artefakt, also der Software, an, deren Format das Versionsverwaltungssystem unterstützt. Eine Möglichkeit besteht darin, eine Readme-Datei anzulegen, die direkt mit dem Quellcode versioniert wird.

Readme-Datei

Eine README-Datei ist im Wesentlichen eine einfache Textdatei, die das Softwareprojekt und wichtige Informationen zur Installation und/oder Nutzung des Projekts kurz zusammenfasst. Außerdem kann der Entwickler darin zusätzliche (Meta-)Informationen ablegen, die von einer automatischen Dokumentation nicht miterfasst werden können. Dazu gehören etwa eine Projektbeschreibung, (grafische) Verwendungsbeispiele für das Projekt, Set-up-Schritte, Ansprechpartner oder Informationen, wie man sich am Projekt beteiligen kann. Heutzutage kommen in vielen Projekten oft einfache Auszeichnungssprachen wie Markdown zum Schreiben der Readme-Datei zum Einsatz. Der Vorteil besteht darin, dass sie dem Dokument eine einheitliche Struktur verleihen, die sowohl leicht zu schreiben und lesen als auch gut durch Programme und Versionsverwaltungen zu verarbeiten ist. Plattformen wie Bitbucket, GitHub oder GitLab können die Readme-Dateien dann verarbeitet und als eine Einstiegsdokumentation auf der Hauptseite des jeweiligen Projekts darstellen.

Automatische Dokumentation

Eine sinnvolle Option ist es, die Dokumentation automatisch aus dem Code generieren zu lassen. Auch wenn sich einfache Textformate wie Markdown oder AsciiDoc ebenso leicht zusammenführen lassen wie Quellcode, bietet die automatische Erzeugung den Vorteil, dass die Dokumentation sich aus dem Quellcode selbst ergibt und sich damit zum Teil von selbst erzeugt. Auf diese Weise befindet sich die Dokumentation automatisch auf demselben Stand wie der jeweilige Quellcode. Weiterhin ist der Aufwand zur Erstellung und Pflege gering.

Automatisches Generieren von Dokumentationen unterteilt sich dabei meist in zwei Teilaspekte. Zum einen wird der Quellcode statisch analysiert, um grundlegende Informationen wie Rückgabetypen und Übergabeparameter daraus zu extrahieren. Zum anderen werden im Code vorhandene Doc-Kommentare analysiert und verarbeitet. Mithilfe dieser Kommentare lässt sich die Dokumentation zusätzlich an...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang