Letzte Änderung am 17. Dezember 2019 by Christoph Jüngling
VBA (Visual Basic for Applications) ist die Programmiersprache von Microsoft, die nahezu identisch im Hintergrund von allem werkelt, das “MS Office” genannt wird. Dadurch kann man mit einem gewissen Sprach-Grundwissen sich schnell in andere Applikationen, die ebenfalls VBA an Bord haben, einarbeiten – oder zumindest bestehenden Code lesen. Da die Namen der Funktionen nicht immer selbsterklärend sind, ist es empfehlenswert, ein paar Zusatzinformationen in Form von Kommentaren direkt im Quellcode zu erfassen. Gemeint ist natürlich nicht so Triviales wie “Dies ist eine Funktion”! Es geht eher um “Was macht diese Funktion?”, und manchmal auch “Wie macht sie das?”, was für die Funktion selbst genauso gilt wie für die Funktionsparameter. Aber davon abgesehen: Natürlich sollte der Name einer Funktion “sprechend” sein.
Die Beschreibung einer VBA-Sub, Function, Methode oder eines Properties erfüllt im wesentlichen folgende Ziele:
- Beschreiben, was die Funktion tut
- Beschreiben, was die Funktion für einen Rückgabewert liefert
- Beschreiben, was die Parameter für einen Sinn haben
- Beschreiben, was die Parameter für einen Typ haben
Da VBA, anders als zum Beipspiel Java, Python oder C/C++/C# keine Blockkommentare kennt, muss der VBA-DocBlock (ich nenne das einfach mal so) in jeder Zeile ein Apostroph am Zeilenanfang haben. Für die Erkennung, dass es sich tatsächlich um einen Funktionskopf handelt, verwende ich einfach drei davon am Anfang und am Ende.
Das hier beschriebene Format ist eine Adaption von Pythons Docstrings. Ein wichtiger Unterschied ist jedoch, dass bei Python der Docstring auf den Funktionskopf folgt, während er bei VBA aufgrund der Verhaltensweise des integrierten Editors davor stehen muss.
Schauen wir uns ein Beispiel an:
'''
' Convert String to double datatype
' Tries to repair invalid formats, raises error if not possible.
'
' :param String strInput: Input string
' :return: Double value of the input string
' :rtype: Double
' :raises: Error 1234
'''
Public Function Str2Dbl(ByVal strInput As String) As Double
Zeile 1 ist der erwähnte dreifache Apostroph, ebenso Zeile 9. Diese Syntax hat in VBA (anders als in Python) keine spezielle Bedeutung. Da dem Compiler aber nach dem ersten Apostroph der Rest der Zeile egal ist, können wir das ungestraft so machen. Für eine spätere automatische Weiterverarbeitung ist das jedoch vorteilhaft, da wir so Anfang und Ende des (eigentlich nicht vorhandenen und daher Pseudo-) Blockkommentars erkennen können. Ich erwarte dabei, dass drei auf einander folgende Apostrophs im restlichen Programmcode nicht vorkommen.
Zeile 2 enthält den Titel der Beschreibung. Dieser könnte je nach Ausgabedesign in einem besonderen Format gesetzt werden. Alle weiteren daran anschließenden Zeilen werden – sofern vorhanden – als Langtext-Beschreibung verstanden.
Die leere Zeile 4 trennt den Beschreibungsteil von den Parametern – primär aus optischen Gründen. Ob hier ein Apostroph am Zeilenanfang steht oder nicht, oder ob die Zeile völlig fehlt, sollte egal sein.
Zeile 5 enthält den im Beispiel einzigen Parameter nach folgendem Schema:
' :param TYP NAME: BESCHREIBUNGEine solche Zeile sollte für jeden Parameter der Funktion existieren, und zwar genau in der Reihenfolge der Parameter.
Zeile 6 definiert den Rückgabewert, Zeile 7 dessen Typ. Bei einer Sub entfallen diese natürlich.
Ich verbinde mit diesem Format die Hoffnung, eines Tages eine einfache Anbindung an Sphinx und dessen sehr umfangreiche Dokumentationsfähigkeiten entwickeln zu können. So könnte man von einem Konzept profitieren, das bereits in der Python-Welt (und nicht nur dort) eine gute Verbreitung hat. Zum Beispiel könnte der Funktionskopf leicht in die Python-Syntax umgesetzt werden, wobei alles weitere der Funktion entfällt. Diese in einem temporären Verzeichnis aufgebauten Rumpf-Dateien würde man dann Sphinx vorsetzen und der alten Dame alles weitere überlassen.
Sphinx unterstützt übrigens noch einiges mehr an Parametern. Auch ließe sich damit sogar das gesamte Benutzerhandbuch erstellen und von einer einzigen Quelle dann CHM, HTML und PDF erzeugen. Aber das ist ein weites Feld und soll zunächst nicht im Fokus stehen. Später vielleicht :-)
Neueste Kommentare