Dokumentationsrichtlinien

von Rainer Becker

Die Firma Wizards & Builders Methodische Softwareentwicklung GmbH verwendet auf Großprojekten statt der bei Visual FoxPro mitgelieferten Anbindung an den Visual Modeller ein eigenes Werkzeug, welches die Übernahme von Klassenbibliotheken und der darin enthaltenen Klassen in das Designwerkzeug "Rational Rose" automatisiert. Dabei werden Texte und Erläuterungen zur Klasse sowie zu deren Methoden (samt Parameter/Rückgabewert) und deren Eigenschaften extrahiert und an die entsprechende Stelle in der Dokumentation innerhalb von Rational Rose gestellt. Damit diese Technik funktioniert, müssen bestimmte Kennzeichnungen für die Texte und Erläuterungen verwendet werden. Diese Kennzeichnungstechnik wird auch als Dokumentationsrichtlinien bezeichnet. Diese Richtlinien möchte ich Ihnen in diesem Artikel gerne vorstellen, da sie auch ohne das genannte Werkzeug für eine einheitliche Art der Klassendokumentation sorgen und man aus solcherart dokumentierte Klassen relativ einfach die entsprechenden Beschreichungen und Kommentare extrahieren kann. Hintergrund ist die Idee, diese Dokumentationsrichtlinien als Standard im Bereich der Softwareentwicklung mit Visual FoxPro zu verbreiten, damit auch andere Firmen diese Notation verwenden und man dann entsprechende Werkzeuge austauschen kann. In einem entsprechenden Vortrag von Joachim Hilgers (dFPUG-Regionalleiter Köln) auf der Visual FoxPro Entwicklerkonferenz wurden diese Dokumentationsrichtlinien aus ebendiesem Grunde bereits schon mal vorgestellt.

Einführung

Es gibt sechs verschiedene Kennzeichnungsmöglichkeiten für Kommentare innerhalb von Quellcode von Prozeduren bzw. Methoden:

  • Dokumentation der Klasse
  • Dokumentation von Eigenschaften
  • Dokumentation von Methoden
  • Dokumentation der Parameter von Methoden
  • Dokumentation des Rückgabewerts von Methoden
  • Dokumentation von Beispielaufrufen

Jede Kennzeichnungsmöglichkeit von Kommentaren hat dabei grundsätzlich folgenden Aufbau:

  • Einleitung des Kommentarbeginns mit "*## "
  • Bezeichnung für die Abschnittsidentifikation des Kommentars
  • Zusatztextschalter/Zusatzklauseln für die Abschnittsidentifikation des Kommentars
  • Variable Parameter für die Abschnittsidentifikation des Kommentars
  • Einleitung des Kommentarendes mit "*## "
  • Endekennzeichen für Kommentarende mit "End"

Der prinzipielle Aufbau eines Kommentars sieht also wie folgt aus:

*##
*## End

Die Syntaxbeschreibung verwendet dabei einen senkrechten Strich für alternative Parameter und ein Leerzeichen für die Trennung gleichzeitig verwendbarer Parameter. Ob ein Parameter optional oder zwingend ist, wird in der Parameterbeschreibung mitgeteilt.

Zusätzlich zu den Kommentarbereichen werden folgende Informationen aus der Klassenbibliothek von Visual FoxPro als Information zur Klasse von dem genannten Werkzeug automatisch übernommen:

  • Name der Klasse
  • Name der Klassenbibliothek
  • Name der Superklasse
  • Name der Basisklasse

Diese Informationen können um weitere Felder aus den Klassenbibliotheken oder um indirekt ermittelbare Informationen erweitert werden, sofern dies als notwendig erachtet wird. Für diese einzeiligen Informationen wurden keine weiteren "Tags" angelegt, da die Eintragung in einer Eigenschaft einfacher und betriebssicherer (keine Tagschreibfehler) erscheint.

Dokumentation der Klasse

Jede Klasse besitzt eine Methode "zClassComment" (dieser Methodenname ist einmalig global frei konfigurierbar, muß aber einheitlich verwendet werden). Diese Methode dient ausschließlich der Dokumentation der Klasse und wird vollständig als Beschreibung der Klasse nach Rational Rose übernommen. Dabei können mehrere Abschnitte mit dem nachfolgenden Aufbau jeweils einmalig eingefügt werden. Sofern keine der Klauseln verwendet wird oder sofern ein Titel verwendet wird, wird die Beschreibung als "Beschreibung lang" übernommen. Der Titel kann dabei beliebig variabel gehalten werden, allerdings darf als erstes Wort weder "Methode" noch "Eigenschaft" noch eine der alternativen Klauseln verwendet werden. Die Unterscheidungen durch verschiedene Klauseln in dieser Dokumentationsmethode spielen in Rational Rose (bis auf den Stereotype) eigentlich keine Rolle sondern werden für die mögliche Extraktion der Angaben in eine WinWord-Dokumentation der Klasse via Rose Soda benötigt. Zusätzlich ist hier ein Dokumentationsabschnitt "Beispiel" zulässig, Beschreibung dieser Klausel siehe weiter unten. Folgende Kommentarklauseln können in dieser globalen Dokumentationsmethode der Klasse verwendet werden:

*##Beschreibung
*##Interface
*##Stereotype <name des stereotype>
*##Eigenschaft <name der eigenschaft> <datentyp> [protected]
*##Beispiel
*##Historie

Diese Kommentarabschnitte haben beschreibende Inhalte gemäß folgender Tabelle:
Bereich Inhaltsbeschreibung
Beschreibung Allgemeine Beschreibung der Klasse
Stereotype Einordnung der Klasse zu einer Kategorie gemäß Liste in Projekthandbuch
Interface Beschreibung der Schnittstelle / Nutzungsprotokoll
History Beschreibung der Klassenhistorie / Versionshistorie
Beispiel Beispiel für die Verwendung der Klasse und deren Methoden
Eigenschaft Ausführliche Beschreibung von Eigenschaften

Ein Kommentar des Typs Beschreibung sieht dann folgendermaßen aus: *##Beschreibung

Der Text landet in der Beschreibung *## End

Ein Kommentar des Typs Stereotype sieht folgendermaßen aus: *##Stereotype Serviceklasse

Aus diesem Abschnitt wird der Stereotyp entnommen. *## End

Ein Kommentar des Typs Interface sieht folgendermaßen aus: *## Interface

Der Text nach der Kennung wird als Beschreibung des Interface interpretiert. *## End

Meist beschränkt man sich dabei allerdings auf einen Kommentar des Typs Beschreibung, ggf. einen Kommentar mit einem Beispielaufruf und dann folgen die Beschreibungen der Eigenschaften der Klasse.

Dokumentation von Eigenschaften

Ebenfalls in der globalen Dokumentationsmethode werden die Eigenschaften der Klasse beschrieben. Diese Beschreibungen landen allerdings nicht im globalen Beschreibungsfeld der Klasse in Rational Rose sondern werden in Rational Rose den jeweiligen Eigenschaften der Klasse zugeordnet. Deshalb ist die Angabe eines Eigenschaftsnamen notwendig. Zusätzlich kann der Typ der Eigenschaft angegeben werden - dieser könnte allerdings auch aus der Namenskonvention der Eigenschaft extrahiert werden; die explizite Angabe überschreibt dann die Definition aus der Namenskonvention. Über eine weitere Klausel ist es möglich, eine in Visual FoxPro wegen der Zugriffsnotwendigkeit aus enthaltenen Klassen nicht als "Protected" markierte Eigenschaft innerhalb des Objektmodells dennoch zu schützen, wenn diese nicht zum offiziellen Interface der Klasse gehört. Der Defaultwert einer Eigenschaft wird direkt aus der Eigenschaft gelesen (unterstellt wird, daß der Initialisierungswert der Eigenschaft auch der Defaultwert ist). Das Format der Syntax lautet dabei wie folgt: *##Eigenschaft <name> <typ> [Protected]
*## End

Die einzelnen Elemente der einleitenden Zeile des Kommentars haben dabei folgende Bedeutung:
Klausel Beschreibung
Eigenschaft Kennung für Dokumentation einer Eigenschaft
<Name> Name der Eigenschaft
<Typ> Optional Typ der Eigenschaft gemäß Typenliste, also Numerisch/Logisch usw.
Protected Optional Schutz von in VFP nicht als Protected markierten Eigenschaften

Hierzu zwei Beispielkommentare, die sich in der allgemeinen Dokumentationsmethode finden: *##Eigenschaft lInit Logical Protected

Die Eigenschaft lInit wird nur intern verwendet, kann aber wegen Zugriff durch enthaltenen Objekte nicht in VFP "Protected" geschaltet werden, gehört aber nicht zum Interface.

*##End
*##Eigenschaft oEA

Diese Eigenschaft wird aufgrund der Namenskonvention als "Objektreferenz" erkannt *## End

Dokumentation von Methoden

Innerhalb einer Methode selbst kann eine Beschreibung der Methode angelegt werden. Diese Beschreibungen landen nicht im globalen Beschreibungsfeld der Klasse in Rational Rose sondern werden in Rational Rose den jeweiligen Methoden der Klasse zugeordnet. Sofern der Entwickler die Dokumentation der Methode nicht in der jeweiligen Methode vornimmt sondern die Dokumentation in die globale Dokumentationsmethode der Klasse stellt, ist die Angabe der Klausel "Methode" sowie eines Methodensnamens notwendig. Anderfalls sind diese Angaben optional. Über eine weitere Klausel ist es möglich, eine in Visual FoxPro wegen der Zugriffsnotwendigkeit aus enthaltenen Klassen nicht als "Protected" markierte Methode innerhalb des Objektmodells dennoch zu schützen, wenn diese nicht zum offiziellen Interface der Klasse gehört. Das Format der Syntax lautet dabei wie folgt: *## Beschreibung [Methodenname] [Protected]
*## End

Hierzu ein Beispielkommentar, der sich am Anfang der eigentlichen Methode befindet: **##Beschreibung

Die Methode wird verwendet, um die eigentliche Initialisierung durchzuführen. Diese Angaben wäre in der globalen Dokumentationsmethode notwendig. *## End

Es wird dabei allerdings empfohlen, innerhalb der jeweiligen Methode zu kommentieren und nicht in der globalen Dokumentationsmethode, da die weiteren Beschreibungsmöglichkeiten sowieso bei der jeweiligen Methode bleiben müssen.

Dokumentation der Parameter

Die Dokumentation der Parameter erfolgt mit einem Kommentarblock je Parameter in der jeweiligen Methode. Falls keine Parameter vorhanden sind, aber dennoch eine Parameterdokumentation erfolgen soll, wird ein Kommentarblock ohne Parameternamen angelegt. Dies kann auch erfolgen, wenn die Parameter nicht einzeln dokumentierbar sein sollten. Die Parameterdokumentation wird in Rational Rose den einzelnen Parametern zugeordnet. Die Parameterdokumentation kann keinesfalls in der globalen Dokumentationsmethode eine Klasse erfolgen. Die Parameter können in willkürlicher Reihenfolge dokumentiert sein. Zusätzlich kann ein Parameter als "Optional" und/oder als "Rückgabewert" gekennzeichnet werden. Das Format der Syntax lautet dabei wie folgt: *## Parameter <name> <typ> [Optional] [Rückgabe]
*## End

Die einzelnen Elemente der einleitenden Zeile des Kommentars haben dabei folgende Bedeutung:
Klausel Beschreibung
<Name> Name des Parameters
<Typ> Datentyp des Parameters gemäß Typenliste
Optional Optional Angabe eines optionalen Parameters
Rückgabe Optional Angabe, der Parameter kann auch für Rückgabe verwendet werden

Hierzu zwei Beispielkommentare, die sich in der Methode selbst befinden: *##Parameter tcUserName Character

Enthalten ist der notwendige Benutzername eines Anwenders. *## End
*## Parameter tcPasswort Character Optional Rückgabe

Enthalten ist das optionale Passwort, welches per Referenz übergeben werden kann, um einen zusätzlichen Rückgabewert zu erhalten. *## End

Dokumentation des Rückgabewerts

Die Dokumentation der Parameter erfolgt mit einem speziellen Kommentarblock innerhalb der jeweiligen Methode. Es wird nur die erste Beschreibung eines Rückgabewertes ausgelesen und verarbeitet. Die Dokumentation des Rückgabewertes wird in Rational Rose der Funktionsrückgabe zugeordnet. Zusätlich kann der Typ des Rückgabewertes angegeben werden - dieser könnte allerdings auch aus der Namenskonvention der Rückgabewerte extrahiert werden, sofern es nur am Methodenende einmalig einen Return-Befehl gibt; die explizite Angabe überschreibt dann die Definition aus der Namenskonvention. Das Format der Syntax lautet dabei wie folgt: *## Rückgabe <typ>
*## End

In <Typ> wird der Typ des Rückgabewerts gemäß Typenliste, also Numerisch/Logisch usw. Hierzu zwei Beispielkommentare, die sich in der Methode selbst befinden: *## Rückgabewert Logical

Die Methode gibt .T. zurück, wenn alles funktioniert hat, andernfalls .F. *## End

Hierzu ein Beispielkommentar, der sich in der eigentlichen Methode befindet: *## Rückgabewert

Es kann auch nur eine allgemeine Beschreibung der Rückgabe erfolgen. Der Datentyp wird in diesem Fall als Logical angenommen. *## End

Dokumentation von Beispielaufrufen

Die Dokumentation eines Beispielaufrufs erfolgt mit einem speziellen Kommentarblock innerhalb der jeweiligen Methode für diese Methode und/oder innerhalb der globalen Dokumentationsmethode für Beispiele betreffs der Einsatzmöglichkeiten der Klasse. Es werden alle Beschreibungsblöcke zu Beispielaufrufen ausgelesen und verarbeitet. Hinter dem Befehlswort Beispiel kann noch ein Titel angegeben werden, der ebenfalls übernommen wird - sinnvoll, wenn mehrere Beispielaufrufe angeboten werden. Das Format der Syntax lautet dabei wie folgt: *## Beispiel
*## End

Hierzu ein Beispielkommentar, der sich in der eigentlichen Methode befindet: *## Beispiel

Die Methode wird aufgerufen mit =this.Methode()

Sonderfall: Die Methode kann auch aufgerufen werden mit =this.parent.&thiscName.Methode() *## End

Anhang Datentypen

Folgende Datentypen können für Parameter und Rückgabewerte verwendet werden:
Datentyp VFP Beschreibung
Character Zeichenketten und Text
Numeric Numerische Daten (auch Integer)
Logical Bool'sche Werte
Object Referenz auf ein Objekt
Date Datumswerte
DateTime Datum und Uhrzeit
Memo Nicht verwendet
General Nicht verwendet
Currency" Währungsdaten
Undefined Nicht definiert bzw. variante Daten
Array Datenfeld