Einführung in Node.js, Folge 19: Dokumentation schreiben
Das Schreiben von Dokumentation gehört zu den eher wenig geliebten Aufgaben von Entwicklern. Trotzdem ist das Thema wichtig, denn eine gute Dokumentation erleichtert die Arbeit mit einer Komponente dramatisch. Wie funktioniert das im Kontext von Node.js?
- Golo Roden
Das Schreiben von Dokumentation gehört zu den eher wenig geliebten Aufgaben von Entwicklern. Trotzdem ist das Thema wichtig, denn eine gute Dokumentation erleichtert die Arbeit mit einer Komponente dramatisch. Wie funktioniert das im Kontext von Node.js?
Bevor man sich mit der Frage befasst, was unter einer guten Dokumentation zu verstehen ist, müssen einige Fragen zur Dokumentation an sich geklärt werden: An wen richtet sie sich? Beschreibt sie die statische Struktur oder das dynamische Verhalten?
Einführung in Node.js
- Folge 1: Node.js installieren
- Folge 2: Erste Schritte
- Folge 3: Module verwenden
- Folge 4: Web-APIs entwickeln
- Folge 5: Middleware
- Folge 6: Auf das Dateisystem zugreifen
- Folge 7: Callbacks verstehen
- Folge 8: Events auslösen und verarbeiten
- Folge 9: Datenbanken ansprechen (NoSQL)
- Folge 10: Praxisbeispiel
- Folge 11: Code analysieren
- Folge 12: Unit-Tests schreiben
- Folge 13: HTTPS und HTTP/2
- Folge 14: Websockets
- Folge 15: Integration-Tests schreiben
- Folge 16: Node.js und Docker
- Folge 17: Streams verwenden
- Folge 18: Eigene Streams schreiben
- Folge 19: Dokumentation schreiben
Die meisten Entwickler neigen dazu, im Zweifelsfall eine Dokumentation als API- beziehungsweise Referenzdokumentation aufzufassen. Das liegt häufig daran, dass sie es von anderen Plattformen und Sprachen wie C# und Java so gewohnt sind.
Eine gute API-Dokumentation zu erzeugen, ist allerdings sehr aufwendig und schwierig – und langweilig. Sie zeichnet sich nämlich vor allem durch Konsistenz und den Fokus auf Details aus, was durch den formalisierten Ansatz allerdings mühsam zu schreiben ist.
Weitaus leichter zu erstellen ist daher eine erzählende Dokumentation, die den Leser auf eine Reise durch die Komponente mitnimmt, ähnlich einem Tutorial. Da der Text in dem Fall lediglich Fließtext ist, der zudem mit vielen Codebeispielen gespickt sein kann, macht das Schreiben auch deutlich mehr Spaß. Außerdem geht es schneller.
Dokumentation ist jedoch nicht alles: Auch gute Kommentare, die erklären, warum Code auf eine gewisse Art geschrieben wurde, sind hilfreich. Dass darüber hinaus auch lesbarer Code an sich schon eine hervorragende Dokumentation darstellt, liegt auf der Hand.
Die größte Herausforderung dabei ist in der Regel eine gute Namensgebung, wie bereits der gängige Satz
"There are only two hard things in computer science: cache invalidation and naming things."
besagt. Es lohnt, sich dafür Zeit zu nehmen. Wie sich das alles im Kontext von Node.js umsetzen lässt, zeigt das folgende Video:
Empfohlener redaktioneller Inhalt
Mit Ihrer Zustimmmung wird hier eine Vimeo-Video (Vimeo LLC) geladen.
Ich bin damit einverstanden, dass mir externe Inhalte angezeigt werden. Damit können personenbezogene Daten an Drittplattformen (Vimeo LLC) übermittelt werden. Mehr dazu in unserer Datenschutzerklärung.
tl;dr: Für eine gute Dokumentation benötigt man nicht zwingend eine API- und Referenzdokumentation. Eine erzählende Dokumentation, die den Leser ähnlich einem Tutorial mit auf eine Reise nimmt, genügt in der Regel völlig und ist leichter zu erstellen. ()
