Frontend Code Dokumentation

← zurück zum Frontend Wiki

Um eine saubere und einheitliche Dokumentation des Codes zu gewährleisten, gelten folgende Konventionen zur Dokumentation des Quellcodes. Die im Code erstellten Kommentare sollten die selben Beschreibungen beinhalten, die auch auf der Schnittstellenseite benutzt wurden. Für ein Beispiel zu den unten abgebildeten Codeschnippseln siehe hier.

Moduldefinition

In den Kopf jeder Datei (direkt über der Moduldefiniton) wird ein mehrzeiliger JDoc-Block eingefügt, der das Modul im Gesamten beschreibt.

Beispiel:

/**
 * Dieses Modul dient dem Verwalten von offline verfügbaren Routen in "Meine Routen".
 */
angular.module('happyHour.persistence.RoutesPersistence', ['LocalStorageModule'])

Funktionen eines Moduls

Vor jeder Funktionsdefinition wird ein JDoc-Block eingefügt, der eine Beschreibung der Funktion, eine Beschreibung aller Parameter, eine Beschreibung des Rückgabewerts sowie den Autor/die Autoren enthält.

/**
 * Fügt eine Route zu "Meine Routen" hinzu und macht sie damit offline verfügbar.
 * 
 * @author Dorothee Nies
 * @param {Route} route Die Route, die in "Meine Routen" gespeichert werden soll.
 * @returns {Boolean} `true` wenn die Route hinzugefügt wurde, `false` wenn das Hinzufügen fehlgeschlagen ist
 */
add: function(route) {

Kommentare im Code

Kommentare im Code selbst sind besonders an jenen Stellen einzufügen, an denen nicht sofort klar ist, wozu diese Zeile(n) benötigt werden. Ansonsten ist durch die Vergabe von sprechenden Variablen- und Funktionsnamen ein möglichst flüssiges Lesen des Codes zu ermöglichen.