Quellcode-Dokumentation in der Softwareentwicklung

In vielen Softwareprojekten, in der Web und App Entwicklung, wird vermehrt ein größeres Augenmerk auf Quellcode-Dokumentation gelegt. Doch viele Kunden fragen sich immer noch, warum man das eigentlich braucht, da Entwickler ja ihren eigenen Code immer verstehen sollten. Die Dokumentation nimmt einen kleinen Teil der Entwicklung ein und sollte immer ordentlich durchgeführt werden, da dies im späteren Verlauf eines Projektes viele Vorteile bringen kann.

Was ist eine Quellcode-Dokumentation?

Um die Vor- und Nachteile der Quellcode-Dokumentation zu beschreiben, ist es vorher wichtig zu wissen und zu verstehen, was das eigentlich ist.

Grundsätzlich handelt es sich hierbei um eine Beschreibung für Funktionen und Abschnitte im Programmiercode einer Anwendung, welche helfen sollen, die Methode zu erklären. In vielen Programmiersprachen befinden es sich immer direkt über der Funktion und beinhalten verschiedenste Parameter. Am häufigsten beinhaltet es Variablen, welche in die Funktion übergeben werden und den Typen, den Namen und eine kurze Beschreibung der Methode, sowie die Rückgabe der Funktion, falls vorhanden, darstellt. Außerhalb der kurzen Beschreibung, oberhalb der Funktion, gibt es auch den Quellcode, welcher einen bestimmten Abschnitt der Methode beschreiben soll. Das ist vor allem wichtig, wenn es um komplexe Rechnungen oder die Berechnung eine Formel geht. So ist es besonders von Vorteil, eine Fourier-Transformation noch einmal kurz zu beschreiben.

Manchmal wird die Funktion der Quellcode-Dokumentation auch benutzt, um Bereiche aufzuteilen. Somit kann man einen Abschnitt der Funktion beispielsweise als initiale Berechnung der Variablen bezeichnen und den Mittelteil als Berechnung. Dann kann besser unterteilt werden, an welcher Stelle der Funktion bestimmte Abschnitte durchgeführt werden.

Außer Methoden besteht natürlich auch die Möglichkeit eine Klasse, Interface oder ein Objekt kurz zu beschreiben. Man sollte hier jedoch aufpassen nicht so viele Kommentare zu schreiben, da das einige Nachteile mit sich bringen kann.

Grundlegend sollte die Quellcode-Dokumentation, genau wie der Quellcode, einheitlich in Englisch geschrieben werden.

Eine weitere Möglichkeit die Quellcode-Dokumentation zu benutzen ist zum Beispiel mit PHPDoc, um eine HTML-Datei zu generieren, welche den ganzen Quellcode und die Dokumentation in einer ausführlichen Listen-Struktur auflistet. Das ist nützlich, um es später als PDF exportieren zu können und so eine gute schriftliche Dokumentation für das Projekt zu haben.

Vor- und Nachteile der Quellcode-Dokumentation

Wie bei vielen Dingen in der Softwareentwicklung, gibt es auch hier viele Vorteile und wenig Nachteile diese Methodik durchzuführen. Im Folgenden wird aufgelistet, welche Vorteile eine Quellcode-Dokumentation mit sich bringt und welche Nachteile diese auch haben könnte.

Vorteile

Durch eine Quellcode-Dokumentation ist Code für andere verständlicher und auch die Einarbeitung fällt leichter. Falls ein Code ordentlich dokumentiert worden ist, kann dieser an andere Agenturen weitergegeben werden und diese können sich leicht in den Code reinlesen. Das ist auch ein weiterer wichtiger Punkt, weshalb ein guter Quellcode auf Englisch geschrieben werden sollte. Weiterhin fällt es Programmierern, welche in ein neues Projekt starten, dann leichter sich einzuarbeiten. Somit kann die Zeit, die für ein längeres Einarbeiten gebraucht worden wäre, für andere Dinge genutzt werden und so können hierdurch Backups aufgebaut werden.

Durch die sorgfältige Dokumentation kann selbst in mehreren Jahren, gerade bei langen Projekten, der Code noch verstanden werden und es muss sich nicht erneut aufwändig eingearbeitet werden.

Quellcode-Dokumentation ist ein Standard in der Softwareentwicklung und sollte deshalb auch immer durchgeführt werden. Zudem kann es dabei helfen, den Code und die Dateien besser zu strukturieren. Eine gute Dokumentation hilft auch dabei, den Code während des Schreibens zu verstehen. So weiß man welche Variablen benötigt und zurückgegeben werden müssen, aber auch wie man diese benennen sollte.

Nachteile

Der größte Nachteil ist der Zeitaufwand, da bei einer ordentlichen Dokumentation viel Zeit in Anspruch genommen wird. Der Code muss bei der Quellcode-Dokumentation immer an der passenden Stellen so beschrieben werden, dass auch andere Entwickler diesen verstehen können. Vor allem das Erstellen neuer Funktion und initialen Entwicklung ist sehr zeitaufwändig.

Die Code-Dokumentation muss ständig gewartet werden. Wenn zum Beispiel die Funktion umgeändert werden muss, in Bezug auf neue Funktionen und Bugfixing, muss auch immer der Quellcode angepasst werden. Da der Code und die Funktionen manchmal stark verkettet sein können, kann sich eine Änderung auf mehrere Stellen im Projekt auswirken. Wenn diese danach nicht wieder umgeändert werden, kann es zu starken Verständnisproblemen kommen.

Quellcode-Dokumentationen können schnell unübersichtlich werden, das kann man besonders gut mit dem Schreiben eines Aufsatzes vergleichen. Man möchte etwas noch genauer beschreiben und auf einmal schweift man vom Thema ab. Gerade bei Quellcode-Dokumentationen ist es wichtig, nur die wichtigsten Stellen kurz und prägnant zu beschreiben. Viele Dokumentationen neigen dazu, zu ausführlich und länger als der Quellcode an sich zu werden.

Fazit

Im Endeffekt ist das Schreiben einer Quellcode-Dokumentation immer von Vorteil, es ist ein Standard, der so gut wie überall vorausgesetzt wird. Sei es nur, um den Code für sich selbst und andere verständlicher zu machen oder um bei späterer Wartung und Überarbeitung viel Zeit einzusparen.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.