Dokumentationskommentare in VBA

Direkt vor die Definition eines Unterprogramms kann ein Kommentar geschrieben werden, der die Schnittstelle  des Unterprogramms beschreibt. Solche Kommentare werden hier mit dem Zeichenpaar "''" eingeleitet wird, um zu kennzeichnen, daß sie zur automatischen Herstellung von Dokumentationsdateien  verwendet werden sollen. Die Schreibweise "''" ist allerdings nicht durch die Programmiersprache VBA  definiert, sondern stellt nur eine Empfehlung  dieser Lektion dar.

Solch ein Kommentar wird auch als Dokumentationskommentar  (documentation comment , doc comment ) bezeichnet. Alle anderen Kommentare kann man auch als Implementationskommentare  (implementation comments ) ansehen, da sie sich mit Aspekten der Implementation  beschäftigen sollten. Diese Unterscheidung und die Festlegungen zur Schreibweise von Dokumentationskommentaren wird allerdings nicht durch die Programmiersprache VBA  festgelegt, sondern stellt eine zusätzliche Empfehlung dar.

Normalerweise wird ein Dokumentationskommentar direkt vor  das zu Dokumentierende geschrieben. So finden sich in dem Beispielmodul "Modul1" Dokumentationskommentare vor jeder Definition.

Modul1

'' Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben 
Private Sub Refrain() 
  Debug.Print "Sim sa la dim, bam ba," 
  Debug.Print "Sa la du, sa la dim -" 
End Sub

'' Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben 
''' Dieses Unterprogramm gibt die ersten drei Strophen  
''' des Liedes "Auf einem Baum ein Kuckuck sass" aus. 
Sub Kuckuck3() 
  ' Kann man das nicht noch verkuerzen? 
  Debug.Print "Auf einem Baum ein Kuckuck, -": Call Refrain 
  Debug.Print "Auf einem Baum ein Kuckuck sass." 
  Debug.Print "Da kam ein junger Jaeger, -": Call Refrain 
  Debug.Print "Da kam ein junger Jaegersmann." 
  Debug.Print "Der schoss den armen Kuckuck, -": Call Refrain 
  Debug.Print "Der schoss den armen Kuckuck tot." 
End Sub

Während ein mit zwei Hochkommas eingeleiteter Dokumentationskommentar für eine Kurzbeschreibung empfohlen wird, wird ein mit drei Hochkommas eingeleiteter Dokumentationskommentar für eine ausführlichere Beschreibung empfohlen.

Dokumentationskommentare werden hier empfohlen, um in einer bestimmten Weise die mit einer Entität verbundene Absicht klarzustellen und ihre Schnittstelle zu definieren. Werkzeuge, die aus VBA -Quelltext automatisch solche Dokumentation entnehmen und in Dokumentationsdateien verfügbar machen, sind denkbar, aber derzeit leider nicht verfügbar (abgesehen von einer undokumentierten Erweiterung von Doxygen ). Dennoch werden solche Dokumentationskommentare hier empfohlen, um die Schnittstelle von Entitäten im Quelltext in einheitlicher Weise zu kennzeichnen. Durch diese Einheitlichkeit wird die Verständlichkeit dieser Kommentare verbessert und eine spätere maschinelle Auswertung unterstützt.

Die Abbildung "Kuckuck3" zeigt, wie eine automatisch aus dem Quellcode erzeugte Dokumentation aussehen könnte.

Modul1 [moegliche Dokumentation, Ausschnitt, gekuerzt]

Modul1 Modul Referenz

Subs 
  Kuckuck3() 
    Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben

Sub Dokumentation 
  Kuckuck3() 
    Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben

    Dieses Unterprogramm gibt die ersten drei Strophen  
    des Liedes "Auf einem Baum ein Kuckuck sass" aus.

Man beachte, daß die Dokumentation keine Beschreibung der Methode "Refrain" enthält, obwohl ihr ein Dokumentationskommentar direkt vorangestellt wurde. Das liegt daran, daß diese Methode nicht öffentlich ist (sie wurde mit dem Schlüsselwort "Private" definiert) und daher nicht zur Schnittstelle, also zu den nach außen sichtbaren (von außen aufrufbaren) Unterprogrammen, der Quelldatei gehört.

Auch der Kommentar "' Kann man das nicht noch verkuerzen?" wird nicht in die Dokumentation aufgenommen, weil er nicht als Dokumentationskommentar gekennzeichnet ist. Dieser Kommentar betrifft ja auch nicht die Schnittstelle des Unterprogramms, sondern seine Implementation.