Montag, 17. Juli 2017

the next big thing: Einführung in Node.js, Folge 19: Dokumentation schreiben


Einführung in Node.js, Folge 19: Dokumentation schreiben

the next big thing 17.07.2017 11:27 Uhr 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?

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:

Einführung in Node.js, Folge 19: Dokumentation schreiben

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.



from heise developer neueste Meldungen http://ift.tt/2vt6T0T
via IFTTT

Keine Kommentare:

Kommentar veröffentlichen