Überblick
Über die Notwendigkeit und den Sinn von Dokumentation besteht weitestgehend Einigkeit, und dennoch fällt diese Aufgabe dem Projektdruck in der Regel als erstes zum Opfer: „Man möge doch in den Quellcode schauen, um zu verstehen, was eine Software oder ein SQL Statement macht.“ Dieser Satz ist oft zu hören. Nicht jeder ist dazu in der Lage, Quellcode und/oder SQL Statements zu lesen. Dokumentation richtet sich schließlich nicht nur an Entwickler, sondern auch Projektmanager, den Fachbereich, das Management. Der eigentliche Grund aber für das häufige Fehlen einer Dokumentation oder eine unzureichende Dokumentation ist, dass es eine unbeliebte Aufgabe ist.
Eine besondere Form der Dokumentation ist die Inline Kommentierung (Inline Dokumentation) von Quellcode und SQL Statements. Sie ist quasi das Netz und der doppelte Boden für die Dokumentation. Fehlt auch die Inline Dokumentation, dann ist eine Anwendung nicht mehr wartbar, wenn das Wissen in den Köpfen der Entwickler nicht mehr vorhanden ist.
Zum Zeitpunkt der Entwicklung mag die Entwicklerin alle wesentlichen Fragen für die Entwicklung des Statements geklärt und im Kopf haben. Dieses Wissen ist allerdings flüchtig. Bereits nach wenigen Wochen fällt es ihr bereits schwer, komplexe Statements nachzuvollziehen. Problematischer stellt sich die Situation in einem Mehrentwicklerprojekt dar.
Nur eine ausreichende Inline Dokumentation unterstützt (andere) Entwickler, eine Aufgabe und den eingeschlagenen Lösungsweg zu erfassen.
Dieser Artikel enthält einige Denkanstöße für die Umsetzung von inline Dokumentation.
Arten der Inline-Kommentare
T-SQL kennt Arten von Inline Kommentaren:
- Zeilenbasierte Kommentare
- Block Kommentare
Zeilenbasierte Kommentare werde mit zwei aufeinander folgenden Bindestrichen eingeleitet und markieren den gesamten folgenden Text auf der rechten Seite der Bindestriche als Kommentar. Die Bindestriche können an jeder beliebigen Stelle in einer Zeile eingefügt werden.
-- Inline Kommentar
Bei einem Text, der sich über mehrere Zeilen erstreckt, sind damit vor jede Zeile die einleitenden Bindestriche zu notieren. Bei zahlreichen zu kommentierenden Zeilen ist das natürlich mit Aufwand verbunden.
Auf der anderen Seite können mehrere Zeilen sehr einfach als Block-Kommentar kommentiert werden. Block Kommentare werden durch einen Schrägstrich gefolgt von einem Stern eingeleitet und einem Stern gefolgt von einem Schrägstrich abgeschlossen. Die einleitende und abschließende Sequenz können an beliebigen Stellen im Code verwendet werden.
/* Block Kommentar */
Wie so oft… auch über die Verwendung der einen oder anderen Kommentar-Funktion wird unter Entwicklern viel diskutiert.
Ich bevorzuge trotz des vermeintlichen Mehraufwandes für die Erstellung der einleitenden Zeichen Sequenz die zeilenbasierte Kommentierungsfunktion. Grund hierfür ist, dass die einleitende Sequenz gerade bei Texten, die sich über mehrere Zeilen erstrecken, einen Kommentar klar als solchen von dem Rest eines Statements abgrenzen. Zusätzlich kann man die Kommentar-Sequenz auch als strukturierendes Element in einem komplexen Statement verwenden.
Bei geschickter Verwendung des Spalteneditors ist der Mehraufwand für die Verwendung der einleitenden Bindestriche minimal. Der Spalteneditor ermöglicht die Erweiterung des Cursors über mehrere Zeilen. Texteingaben werden auf alle Zeilen, über die sich der Cursor erstreckt, angewendet und es können gleich mehrere Zeilen auf einmal aus- oder auch wieder einkommentiert werden. Siehe hierzu auch Funktionale Design (Ästhetik) von SQL.
Hilfreiche Tastenkombination sind hier übrigens die Tastenkombination Strg+K+C (mit C für Comment) und Strg+K+U (mit U für Uncomment). Die erste Tastenkombination kommentiert die Zeilen, über die sich die aktuelle Selektion erstreckt. Die zweite Tastenkombination hebt die Kommentierung wieder auf.
Beispiele
Dieses Kapitel gibt drei Beispiele für die Verwendung der Inline Dokumentation und möchte die Vor- und Nachteile der jeweiligen Technik aufzeigen:
- Keine einheitliche Inline Dokumentation
- Parallele Inline Dokumentation
- Vorlage für Inline Dokumentation mit Kommentaren
Keine einheitliche Inline Dokumentation
Das nachfolgende Beispiel zeigt eine Inline Dokumentation, wie sie vermutlich häufig anzutreffen ist. Es gibt keine einheitliche Verwendung der Kommentierungs-Funktionen, keine einheitliche Einrückung der Kommentare und alle Kommentare erstrecken sich auf die vollständige Zeile. Dieses mittelkomplexe Statement ist – trotz guter Formatierung des eigentlichen Statements – wegen der unstrukturierten Inline Dokumentation nur schwer zu lesen. Die Komplexität des SQL-Statements liegt in der Verwendung einer rekursiven Common Table Expression (CTE) und der entsprechenden Dokumentation dieses Features bzw. seiner Verwendung. Das Statement kann in der Datenbank AdventureWorksDW2017 ausgeführt werden.
Parallele Inline-Dokumentation
Das exakt gleiche Statement ist in dem folgenden Beispiel mit einer parallelen Inline Dokumentation überarbeitet worden. Die parallele Inline Dokumentation zeichnet sich dadurch aus, dass rechts hinter dem Statement ein Block für die Inline Dokumentation vorgesehen ist und dieser durch die Verwendung der zeilenbasierten Kommentierungszeichenfolge (doppeltes Minus) eingerichtet wird. Die Kommentierungszeichenfolgen werden über alle Zeilen linksbündig ausgerichtet.
Einige Eigenschaften dieser Variante lassen sich wie folgt benennen:
- Das SQL- Statements ist kompakt und zeichnet sich durch eine gute Lesbarkeit aus.
- Die Inline-Kommentare/Dokumentation unterbrechen nicht das SQL-Statement und behindern daher nicht die Lesbarkeit und Verständlichkeit.
- Besteht ein direkter Bezug zwischen dem Code und dem Kommentar in der gleichen Zeile, kann dieser Bezug durch eine vorangestellte Zeichensequenz kenntlich gemacht werden (z.B. >>).
- Längere Kommentare sollten über Spiegelpunkte strukturiert gegliedert und nicht als Fließtext eingefügt werden. Als Spiegelpunkt-Zeichen kann das Hash-Zeichen (#) verwendet werden.
- Die Länge eines Kommentares sollte nicht zu lang sein, um zu vermeiden, dass der Entwickler zum Lesen der Kommentare übermäßig horizontal navigieren muss. Längere Kommentare sind umzubrechen und linksbündig zu der vorigen Zeile einzurücken. Die horizontale Navigation ist ungleich schwerer durchzuführen als die vertikale Navigation über das Mausrad oder die Bild auf– und Bild ab-Tasten.
Vorlage für Inline-Dokumentation mit Kommentaren
In dem folgenden Beispiel wurden die wesentlichen Eigenschaften der Inline Dokumentation aus dem zweiten Beispiel als Kommentar eingefügt.
