Wiki der Access Code Library

Gemeinsam zu mehr Effizienz in der Anwendungserstellung

Richtlinien für die Code-Dokumentation

Aus Access Code Library
Version vom 22:40, 20. Apr. 2010 bei Josef Pötzl (Diskussion | Beiträge)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
Wechseln zu: Navigation, Suche

Ein wichtiger Bestandteil der Code-Bibliothek ist die Dokumentation der Module. Der Großteil dieser Code-Dokumentation kann in den Modulen selbst gestaltet werden. Falls genauerer Anleitungen mit Bildern erforderlich sind, kann dieser Teil ins Wiki verlagert werden.

Was wird dokumentiert

  • Pflicht
    • Modul- u. Klassenbeschreibung
    • Public-Elemente von Modulen und Klassen
  • Optional
    • Hinweise im Code

Kommentare im Code sollten das Lesen des Codes unterstützen. Es ist allerdings nicht notwendig in einer If-Anweisung wie if x = y then einen Kommentar wie "prüfen ob x = y ist" anzufügen. Den Ablauf einer Prozedur sollte grundsätzlich aus dem Code erkennbar sein. Kommentare sollten nur unterstützend wirken. Sobald umfangreiche Kommentare für das Verstehen eines Prozedurablaufs notwendig werden, ist das meist ein Anzeichen für eine notwendige Aufteilung der Prozedur in mehrere überschaubare Prozeduren.

Wie wird dokumentiert

Die Code-Dokumentation für die Public-Elemente ist mit Doxygen-Tags im Module bzw. in der Klasse zu gestalten, damit eine html-Dokumentation bzw. eine chm-Datei automatisch erstellt werden kann. Der Doxygen-Kommentarblock wird für Klassen und Module im Kopf des jeweiligen VBA-Codemoduls eingefügt. Für Prozeduren in Modulen und Eigenschaften, Methoden und Ereignisse in Klassen wird der Doxygen-Block direkt über die Dekalrationszeile eingefügt.

Ein Doxygen-Block wird mit '/** eingeleitet und endet mit '**/ zwischen diesen Zeilen dürfen nur Kommentarzeilen stehen.

Kommentare innerhalb von Prozeduren, die nicht in der HTML-Dokumentation landen sollen, dürfen nicht mit den Doxygen-Kennungen eingrenzt werden.

Beispiele:

Module

Modulkopf

'---------------------------------------------------------------------------------------
' Module: %Modulname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung des Moduls %
' </summary>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
' \ingroup %Gruppen-Kennung%
'**/                                            '<-- Ende Doxygen-Block
'<codelib>                                      '<-- Start CodeLib-Block
'  <file>%Pfad/Dateiname%</file>                '<-- CodeLib-Abladeort und Kennung
'  <license>_codelib/license.bas</license>      '<-- Verweis auf die Lizenz
'  <use>%Pfad/Dateiname%</use>                  '<-- Im Code-Modul benötigtes Element
'  <replace>%Pfad/Dateiname%</replace>          '<-- zu ersetzendes Code-Modul
'  <test>%Pfad/Dateiname%</test>                '<-- Verweis auf ein Test-Modul
'</codelib>                                     '<-- Ende CodeLib-Block
'---------------------------------------------------------------------------------------
' %Hinweise, die nicht in der Html-Dokumentation stehen sollen, 
'  aber für einen Programmierer dieses Moduls hilfreich sind.%
'

Option Compare Text
Option Explicit
 
[...]
  • <file> ist eine Pflicht-Angabe
  • <license> kennzeichnet die Lizenz, unter der der Code freigegeben wird
  • <use> ist notwendig, wenn Abhängigkeiten existieren (darf mehrmals verwendet werden).
  • <replace> kommt zum Einsatz, wenn ein bestimmtes Modul überschrieben werden soll.
  • <test> gibt ein Test-Modul (für Unit-Tests) an (darf mehrmals verwendet werden).
  • <ref> gibt eine erforderliche Bibliotheks-Referenz an (darf mehrmals verwendet werden).
    Beispiel:
    ' <ref><name>DAO</name><major>5</major><minor>0</minor><guid>{00025E01-0000-0000-C000-000000000046}</guid></ref>

Prozeduren

Sub
'---------------------------------------------------------------------------------------
' Sub: %Prozedurname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Funktion (Aufgabe der Funktion) %
' </summary>
' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
'**/                                            '<-- Ende Doxygen-Block
'---------------------------------------------------------------------------------------
Public Sub %Prozedurname%(ByVal %Parameter 1% As %typ%)
[...]
Function
'---------------------------------------------------------------------------------------
' Function: %Prozedurname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Funktion (Aufgabe der Funktion) %
' </summary>
' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param>
' <param name="%Parameter 2%">%Beschreibung des 2. Parameters</param>
' <returns>%Beschreibugn des Rückgabewertes</returns>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
'**/                                            '<-- Ende Doxygen-Block
'---------------------------------------------------------------------------------------
Public Function %Prozedurname%(ByVal %Parameter 1% As %typ%, ByVal %Parameter 2% As %typ%) As %typ%
[...]

Klassen

Klassenkopf

'---------------------------------------------------------------------------------------
' Class: %Klassenname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Klasse %
' </summary>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
' \ingroup MISC                                 '<-- Zuordnung zur Doxygengruppe
'**/                                            '<-- Ende Doxygen-Block
'<codelib>                                      '<-- Start CodeLib-Block
'  <file>%Pfad/Dateiname%</file>                '<-- CodeLib-Abladeort und Kennung
'  <license>_codelib/license.bas</license>      '<-- Verweis auf die Lizenz
'  <use>%Pfad/Dateiname%</use>                  '<-- Im Code-Modul benötigtes Element
'  <replace>%Pfad/Dateiname%</replace>          '<-- zu ersetzendes Code-Modul
'  <test>%Pfad/Dateiname%</test>                '<-- Verweis auf ein Test-Modul
'</codelib>                                     '<-- Ende CodeLib-Block
'---------------------------------------------------------------------------------------
' %Hinweise, die nicht in der Html-Dokumentation stehen sollen, 
'  aber für einen Programmierer dieses Klasse hilfreich sind.%
'

Methoden

Für Methoden gilt die gleiche Syntax wie bei einer Function bzw. Sub in einem Modul

Eigenschaften

'---------------------------------------------------------------------------------------
' Property: %Eigenschaftsname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Eigenschaft %
' </summary>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
'**/                                            '<-- Ende Doxygen-Block
'---------------------------------------------------------------------------------------
Public Property Get %Eigenschaftsname%() As %typ%

Ereignisse

'---------------------------------------------------------------------------------------
' Event: %Ereignisname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung des Ereignisses %
' </summary>
' <param name="%Parameter 1%">%Beschreibung des 1. Parameters</param>
' <param name="%Parameter 2%">%Beschreibung des 2. Parameters</param>
' <remarks>
' % Detailbeschreibung und Zusatzinformationen %
' </remarks>
'**/                                            '<-- Ende Doxygen-Block
Public Event %Ereignisname%(ByVal %Parameter 1% As %typ%, ByVal %Parameter 2% As %typ%)

Sonstiges

Enum-Anweisung

'---------------------------------------------------------------------------------------
' Enum: %Enumname%
'---------------------------------------------------------------------------------------
'/**                                            '<-- Start Doxygen-Block
' <summary>
' % Kurzbeschreibung der Aufzählung %
' </summary>
' <list type="table">
'   <item><term>%Element 1% (1)</term><description>%Beschreibung Element 1%</description></item>
'   <item><term>%Element 2% (2)</term><description>%Beschreibung Element 2%</description></item>
' </list>
'**/                                            '<-- Ende Doxygen-Block
'---------------------------------------------------------------------------------------
Public Enum %Enumname%
   %Element 1% = 1
   %Element 2% = 2
End Enum

Hinweise

Der Doxygen-Kommentarblock kann bei Bedarf mit weiteren Doxygen-Tags erweitert werden. Auf Auflistung aller Tags gibt es im Doxygen-Manual.

Für vereinfachtes Ergänzen der Kommentarblöcke ist das VBE-COM-Add-In Mz-Tools hilfreich.

Weiterführende Links: Doxygen-Hilfe : Doxygen Manual der offiziellen Doxygen-Website