Statistik

Wie JSDoc der IDE hilft, dem Entwickler zu helfen

JavaScript (JS) ist bekannterweise eine nicht typsichere Sprache. Variablen werden ohne Typ definiert. Man kann einer Variable nicht ansehen, von welchem Datentyp der Wert ist. Die IDE kann uns bei der Entwicklung nicht so unterstützen, wie sie es für eine typsichere Sprache wie z.B. Java kann. Mit JSDoc können wir der IDE aber helfen, uns zu helfen.

Wie JSDoc der IDE hilft, dem Entwickler zu helfen

Mittlerweile gibt es mehrere Erweiterungen von JS, die Datentypen in JS einführen und es damit typsicher machen. Die bekannteste dürfte TypeScript sein. Wenn man aber JS ohne Erweiterungen nutzen muss, bringt einen das nicht weiter. Ohne Erweiterungen wie TypeScript wird JavaScript nicht typsicher. Muss man JS nativ nutzen, helfen nur Konventionen, wie z.B. Verschlüsselung des Datentyps im Variablennamen (iAlter integer, fBetrag float, sName string) oder eine Dokumentation im Sourcecode. Mit beidem ist das so eine Sache. Namenskonventionen werden schon mal vergessen und rutschen auch bei einem Codereview schnell durch. Sourcecode Dokumentation ist oft schneller veraltet, als der Code geschrieben ist. Selbst wenn Namenskonventionen und Sourcecode Dokumentation konsequent durchgehalten werden und aktuell sind, kann die IDE damit nichts anfangen.

Schön wäre es, wenn die Dokumentation der IDE helfen könnte, mir zu helfen. Damit würde die Wahrscheinlichkeit steigen, dass die Sourcecode Dokumentation aktuell und richtig ist. Dafür gibt es JSDoc. JSDoc ist eine standardisierte Weise zur Dokumentation des Sourcecodes. Die Syntax ist analog Javadoc. JSDoc besitzt auch einen Generator zum Generieren einer separaten Dokumentation im html Format.

Ein Feature von JSDoc ist die Dokumentation von Datentypen. Diese Dokumentation werten IDEs wie WebStorm, IntelliJ IDEA, NetBeans und Eclipse aus. Die IDEs wissen damit, welchen Datentyp ein Funktionsparameter hat, ob der Parameter ggfl. optional ist und welchen Datentyp die Rückgabe einer Funktion hat. Auch Json-Objekte können mit JSDoc beschrieben werden. Erwartet eine Funktion ein Json-Objekt oder liefert sie ein Json-Objekt zurück, kennt die IDE den Aufbau des Json Objekts und macht im Content Assist die passenden Vorschläge.

Mit JSDoc wird JavaScript nicht typsicher. JSDoc zusammen mit der IDE unterstützt uns Entwickler aber beim Schreiben des Codes. Das erhöht die Effizienz bei der Entwicklung, verbessert die Wartbarkeit und reduziert die Fehlerwahrscheinlichkeit.
Wie sieht das nun konkret aus?

Wie JSDoc der IDE hilft, dem Entwickler zu helfen
Abbildung 1 Funktion f1

Die Funktion f1 hat drei Parameter, kundennummer, name und geburtsdatum. Der jeweilige Datentyp ist in den geschweiften Klammern angegeben. Als Rückgabe hat die Funktion ein Json-Objekt. Die Struktur des Json-Objekts ist mit dieser Typedefinition definiert.

Wie JSDoc der IDE hilft, dem Entwickler zu helfen
Abbildung 2 TypeDef

Bei Aufruf der Funktion

Wie JSDoc der IDE hilft, dem Entwickler zu helfen
Abbildung 3 Aufruf Funktion f1

weiß die IDE, dass „result“ ein Json-Objekt mit der in JSDoc definierten Struktur ist. Der Content Assist kann die passenden Properties vorschlagen.

Wie JSDoc der IDE hilft, dem Entwickler zu helfen
Abbildung 4 ContentAssist

JSDoc ist natürlich wesentlich mehr als nur Funktionsbeschreibungen und Typedefinitionen. Für einen Entwickler sind diese beiden Features aber sehr hilfreich und es ist ein erster Schritt in Richtung Dokumentation des JavaScript Sourcecodes. Das freut den Architekten und alle, die den Code später warten müssen.

Ansprechpartner: Marco Königstein

Das S&N Invent Marketing-Team

Ihre Ansprechpartner für alle Fragen rund um unsere Themen und Veröffentlichungen

Barbara Buthmann

Barbara Buthmann
Marketing

Nicole Heyne

Nicole Heyne
Marketing