Im allgemeinen wird auf sprechende Namen gesetzt, sodass die Funktionen selbsterklärend sind.
Bei Abfragefunktionen, mit welcher der Anwender einen Wert anfordert, gibt der jeweilige Präfix des Funktionsnamens Aufschluss, von welchem Typ der Rückgabewert sein wird.
Funktionen die mit einem get beginnen, geben wenn möglich den gewünschten Wert ansonsten ein undefined zurück.
Funktion: getXYZ Ergebnis: Wert oder undefined
Beispiele: getElementByIndex, getIndexOfElement, getDomElement, getDomElements
Funktionen die mit einem maybe beginnen, geben im Erfolgsfall ein Just mit den gewünschten Wert, ansonsten ein Nothing zurück.
Funktion: maybeXYZ Ergebnis: Just(Wert) oder Nothing
Beispiele: maybeDivision, maybeTruthy, maybeDomElement, maybeNumber
Funktionen die mit einem either beginnen, geben im Erfolgsfall ein Right mit dem Resultat, ansonsten ein Left mit einer Fehlermeldung zurück.
Funktionen: eitherXY Ergebnis: Left(Fehlerbehandlung) oder Right(Wert)
Beispiele: eitherTruhty, eitherNotNullAndUndefined, eitherDomElement, eitherNumber, eitherFunction
Alle Konstruktionen sind mit dem Keyword const definiert. Somit können diese Variablen nicht überschrieben/verändert werden.
Bei Konstruktionen soll darauf geachtet werden, dass diese aus reinen Funktionen bestehen.
Objekte und Arrays werden nicht verwendet. Ausnahme gibt es bei Funktionen, die als Brücke zwischen den Welten Lambda Kalkül und JavaScript dienen. Das sind die Convert-Funktionen:
converElementsToStack
Für die Zahlen die Transformation-Funktionen zwischen Church- und JavaScript-Zahlen:
Bei den erstelleten Funktionen kommt es häufig vor, dass die Impementation aus einer einzigen Codezeile besteht. Die Leserlichkeit kann zum Teil darunter leiden weil die Zeile zu lang ist. Richtiges formatieren der Funktionen mit Zeilenumbrüchen, Einrückungen und Leerzeichen sind daher empfehlenswert und JavaScript ist dabei ziemlich unempfindlich. So darf der Code schön arrangiert werden, denn gut ausgerichteter Code fördert die Leserlichkeit immens.
Gegeben ist ein nicht formatierter Code: Ein Observable mit ein paar Listener, die hinzugefügt werden. Es ist schwer auf einem Blick zu sehen wieviel und welche Listener es sind, da sie in einer Reihe aufgelistet sind.
Wir sind gewohnt das Code Zeilen linksbündig ausgerichtet sind. Diese Struktur wird hier neu definiert. Wenn bei einer Funktion es zu mehrere Funktionsverknüpfungen mit Wertübermittlung kommt, ist es empfehlenswert diese Aufrufe untereinander zu schreiben.
Einrücken der Funktion unterhalb der Haupt-Funktion in einer Linie plus einem Leerzeichen, macht es erkennbarer, dass sie zueinander gehören und darauf aufbauen.
Es ist schöner und lesbarer, wenn es zwischen den Werten in den Klammern mindestens ein Leerzeichen gibt. Somit bekommen alle Werte dieselbe Präsenz. Es ist dabei empfehlenswert die Klammern auf einer Linie untereinander zu bringen.
JavaScript versucht zwar selber eine Semikolon am Ende einer Anweisung einzufügen, wenn der Programmierer keine gesetzt hat. Hier ist aber nicht klar, ob die Anweisung für JavaScript fertig ist, denn es wäre mittels Funktionskomposition möglich immer weitere Funktionen anzufügen. Es ist darum besser immer ein Semikolon zu setzen, nicht nur um JavaScript zu signalisieren, dass es hier zu ende ist, sondern auch für die Leserlichkeit.
Das Dokumentieren der Funktionen mit der JSDoc bringt einige Vorteile. In den ersten Zeilen steht ein Text mit zwei bis drei Sätze, der fachlich erklärt was die Funktion tut. Anschliessend wird mit den JSDoc-Tags die Dokumentation mit Hinweisen erweitert:
@haskell Typ deklaration in Haskell Notation
@sideffect wenn die Funktion einen Side-Effekt auslöst wie zum Beispiel ein Log auf die Konsole
@function markiert eine Funktion explizit als eine Funktion. Optional: Kann man der Funktion einen zweiten Name geben (Alias)
@param für das erste Argument (hilfreich für die Pop-Up Informationen)
@return wenn die Funktion mehrere Argumente/Funktionen erwartet (hilfreich für die Pop-Up Informationen)
@example Beispiele wie die Funktion angewendet wird
Beispiel JS-Dokumentation an der Funktion getElementByIndex
In der IDEA (hier Intellij) wird die Dokumentation dementsprechend angezeigt:.
Ein sehr praktischer Vorteil, nebst der Dokumentation, sind die Pop-Up Informationen welche dem Anwender beim benutzen der Funktionen angezeigt werden. Der Anwender wird informiert, welcher Parameter als nächstes erwartet wird.
