Code-Dokumentation: The Complete Beginner’s Guide

Sie sind ein bisschen in Ihrem ersten Programmierjob und die Dinge werden einfacher. Zuerst hat der gesamte Code, mit dem Sie sich befassen mussten, Sie vielleicht überwältigt und verwirrt, aber Sie fangen an, den Dreh raus zu bekommen. Das ist toll! Jetzt fragen Sie sich, wie Sie den Code, den Sie schreiben, auf die nächste Ebene bringen können. Während es viele Dinge über Ihren Programmierstapel zu lernen gibt, von denen viele Sie zu einem besseren Programmierer machen, gibt es einige, die Ihnen helfen werden, egal in welchem Stapel Sie arbeiten. Eine davon ist die Codedokumentation.

Viele Entwickler schreiben nicht genügend Dokumentation, entweder weil sie den Wert nicht sehen oder weil sie das Gefühl haben, keine Zeit zu haben. Sie müssen nicht einer dieser Entwickler sein. Mit ein wenig Zeit und viel Übung können Sie Ihrem Code eine Dokumentation hinzufügen, die das Lesen sowohl für Sie als auch für alle anderen, die mitkommen, zu einer Freude macht.

Gute Dokumentation gibt es in vielen Formen

Wenn die meisten Entwickler an Codedokumentation denken, denken sie an Kommentare. Kommentare können wertvolle Ergänzungen zum Code sein, aber sie sind nicht die einzige Definition von Dokumentation. Dokumentation ist alles, was Sie zusätzlich zu Ihrem Code schreiben, um jemand anderem zu helfen, zu verstehen, wie es funktioniert. Sie denken vielleicht nicht so darüber nach, aber ein gutes Beispiel für Codedokumentation ist eine README-Datei. Ein gutes Beispiel für grundlegende Dokumentation ist der Express.js README-Datei. Es beantwortet einige wichtige Fragen zum Framework und erklärt Ihnen, wie Sie es in Ihr Projekt aufnehmen können, wie Sie es installieren und wie Sie Tests ausführen.

Gute Dokumentation kann auch in Form von API-Dokumentation vorliegen. Noch einmal, Express.js bietet ein gutes Beispiel. Diese Version der Dokumentation ist eher eine Referenzbibliothek für Entwickler, die das Framework verwenden. Hier finden Sie Antworten auf Fragen, was einzelne Funktionen tun und was unterschiedliche Parameter für diese Funktionen bedeuten. Ohne diese Qualitätsdokumentation hätten Express nicht annähernd so viele Teams, die sie verwenden.

Und natürlich können Sie auch Inline-Kommentare verwenden, um Code zu dokumentieren. Diese Art von Kommentaren wird normalerweise nicht verwendet, um Personen außerhalb Ihres eigenen Teams über den Code zu informieren. Stattdessen sind sie nützlich, um Ihren Teamkollegen oder Ihrem zukünftigen Selbst zu erklären, was in einem bestimmten Code passiert.

Warum Sie Ihren Code dokumentieren sollten

Wie oben erwähnt, verstehen viele Entwickler den Zweck der Codedokumentation nicht. Sie werden argumentieren, dass guter Code selbstdokumentierend sein sollte und dass Sie ihn nicht erklären müssen. Diese Leute sind, mit einem Wort, falsch. Die Wahrheit ist, dass eine gute Dokumentation ein wesentlicher Bestandteil jeder Codebasis ist. Warum? Weil die Leute nicht Ihren gesamten Code lesen müssen, um zu verstehen, was er tut. “Menschen” in diesem vorherigen Satz können sich auf jeden beziehen, einschließlich Ihres zukünftigen Selbst.

Die Wahrheit ist, dass oft die “Leute”, die Code verstehen müssen, nachdem er geschrieben wurde, Sie sind. Dieses kleine Stück Logik, das so klug schien, als Sie es vor sechs Monaten geschrieben haben, könnte heute schwer zu verstehen sein. Wenn Ihr Code gut dokumentiert ist, müssen Sie keine Zeit damit verbringen, zu verstehen, was er tut. Sie können ein paar Sekunden damit verbringen, sich die Beschreibung anzusehen und dann zu dem zurückzukehren, woran Sie gerade arbeiten.

Wenn Sie das Glück haben, an Code zu arbeiten, der von Dutzenden oder Hunderten von Entwicklern verwendet wird, ist eine gute Dokumentation noch wichtiger. Das Leben Ihrer Benutzer wird durch das Schreiben guter Dokumentation erheblich verbessert, und sie werden es Ihnen danken. Buchstäblich!

Der Schlüssel zu erinnern ist, dass eine gute Dokumentation spart mehr Zeit, als es braucht, um es zu schreiben. Es könnte Ihre Zeit sein, oder es könnte die Zeit der Teammitglieder sein, oder sogar Leute, die Sie nie treffen werden. Manchmal hilft Ihnen das Schreiben von Dokumentation sogar dabei, einen Teil Ihres Codes zu erkennen, der zu kompliziert ist, damit Sie ihn vereinfachen können.

Einige häufige Dokumentationsfehler

Als Junior-Entwickler müssen Sie Zeit damit verbringen, zu lernen, was Dokumentation effektiv macht. Die gute Nachricht ist, dass Sie von Menschen lernen können, die vor Ihnen gegangen sind, so dass Sie häufige Fehler vermeiden können.

Unterdokumentation

Ein häufiger Fehler, den ich bei der Codedokumentation sehe, besteht darin, Informationen zu dokumentieren, die bereits deutlich sichtbar sind. Zum Beispiel fügen faule Entwickler einer Funktion “Dokumentation” hinzu, indem sie einen Block hinzufügen, der den Namen einer Funktion sowie die Namen der einzelnen Parameter und ihrer einzelnen Typen enthält. Diese Art der Dokumentation ist nutzlos! Es dauert Sekunden, bis jemand den Namen der Funktion und die erforderlichen Parameter gelesen hat. Das ist keine Dokumentation, es ist nur Wiederholung. Stattdessen sollte die Dokumentation eine kurze Information darüber enthalten, was die Funktion tut und wie jeder Parameter das Verhalten der Funktion ändert oder warum sie benötigt wird.

Überdokumentation

Das entgegengesetzte Muster kann ebenfalls ein ernstes Problem sein. Um zu vermeiden, zu wenig Dokumentation zu schreiben, schreiben einige Entwickler gerne die Erklärung für jedes winzige Stück Logik auf, das in einer Funktion enthalten ist. Sie dokumentieren akribisch jede Begründung, die in die Erstellung der Funktion eingeflossen ist. Wenn sie fertig sind, haben sie möglicherweise genauso lange die Funktion geschrieben wie die Dokumentation. Schlimmer noch, die Dokumentation ist oft schwer zu verstehen und dauert genauso lange wie das Lesen des Codes. Auch diese Art der Dokumentation ist Zeitverschwendung. Stattdessen gibt eine gute Dokumentation eine grundlegende Erklärung sowohl des Was als auch des Warum. Wenn es besonders schwierige Teile des Codes zu verstehen gibt, sollte die Dokumentation nur diese Teile erklären.

Verlassen Sie sich auf Tests, um

Gelegentlich werden Sie auf jemanden stoßen, der argumentiert, dass die beste Form der Dokumentation Komponententests sind. Dieser Ansatz hat ein großes Manko: Das Lesen von Komponententests ist oft genauso schwierig wie das Lesen von Code selbst. Jeder Entwickler, der lernen möchte, was Ihr Code tut, wird einen großen ersten Schritt haben, während er alle Ihre Komponententests jagt und liest. Viele werden einfach aufgeben, bevor sie das erreichen, was sie sich vorgenommen haben. Komponententests sind zwar eine wertvolle Ergänzung zu jeder Codebasis, ersetzen jedoch keine gute Dokumentation.

Möglichkeiten, die Dokumentation auf die nächste Stufe zu heben

Wenn Sie an einer großen Codebasis arbeiten, kann sich die Codedokumentation entmutigend anfühlen, insbesondere wenn Sie bis zu diesem Zeitpunkt nicht sorgfältig Code dokumentiert haben. Es könnte sich anfühlen, als würdest du versuchen, den Ozean zu kochen. Wenn Sie über eine große Codebasis verfügen oder wissen, dass eine gute Dokumentation von entscheidender Bedeutung ist, sollten Sie automatisierte Codedokumentationstools untersuchen. Diese Tools vereinfachen den Prozess des Schreibens konsistenter, guter Dokumentation für ein ganzes Team drastisch. Ein Tool wie GhostDoc wird Ihren Code intelligent betrachten und Vorlagen verwenden, die von Ihrem Team erstellt wurden, um Ihre Dokumentation mit ein paar Tastendrücken zu starten. Automatisierte Dokumentationstools beseitigen einen der anderen häufigen Gründe, sich dem Schreiben von Dokumentation zu widersetzen: Es braucht zu viel Zeit.

Sobald Sie über eine konsistente Dokumentation verfügen, können Sie diese mit anderen Tools problemlos freigeben. Automatisierte Dokumentationstools erleichtern die Entwicklung einer guten Dokumentation für Dinge wie öffentliche APIs, die Ihr Code bereitstellt.

Starten Sie noch heute

Das Schreiben einer großartigen Dokumentation ist viel einfacher als das Schreiben von Code. Im Gegensatz zu Code ist Dokumentation kein Alles-oder-Nichts-Unternehmen. Beginnen Sie mit dem Ziel, jeden Tag eine gute Dokumentation für eine Funktion zu schreiben. Diese Art von Übung baut gesunde Gewohnheiten auf, und Sie werden die Auszahlung später sehen, wenn Sie viel weniger Zeit damit verbringen, Teile Ihrer Codebasis zu verstehen. Im Laufe der Zeit wird es sich falsch anfühlen, wenn Sie Code schreiben, der keine gute Dokumentation enthält. Sie werden Ihren Mitarbeitern während der Codeüberprüfung Möglichkeiten zur Verbesserung der Dokumentation aufzeigen. Eine kleine Gewohnheit verbessert den Code Ihres Teams für Ihr gesamtes Unternehmen.

Erfahren Sie, wie GhostDoc Ihnen helfen kann, Ihre XML-Kommentare zu vereinfachen und qualitativ hochwertige Hilfedokumentationen zu erstellen und zu pflegen.

Über den Autor

Eric Boersma

Beitragender Autor

Eric Boersma ist ein Softwareentwickler und Entwicklungsmanager, der alles getan hat, von der IT-Sicherheit in der Pharmazie über das Schreiben von Intelligence-Software für die US-Regierung bis hin zum Aufbau internationaler Entwicklungsteams für gemeinnützige Organisationen. Er liebt es, über die Dinge zu sprechen, die er auf dem Weg gelernt hat, und er hört gerne zu und lernt auch von anderen.