Unten finden Sie einige zusätzliche Erklärungen über den in einem Stored Procedure verwendeten Dokumentations-Header:
Tags
Das Skript wählt Zeilen aus, die wie folgt beginnen: -- DID -
Dies ist die Kennung, mit der eine Dokumentationszeile beginnen sollte. Es ist die Abkürzung von „Datenintegrationsdokumentation“. Hinter diesem Teil sollte ein Indikator folgen, der angibt, was in der Zeile dokumentiert wird. Die maximale Länge der gesamten Zeile sollte 200 Zeichen nicht übersteigen. Dies soll vermeiden, dass der Inhalt abgeschnitten wird.
Die Tags können mehrmals wiederholt werden. Der Inhalt wird im Skript auf Basis der Reihenfolge, in der er in der Routine auftritt, aneinandergereiht.
Die Tags müssen nicht an einem spezifischen Ort in der Routine angegeben werden. Sie können überall im Skript erscheinen. Vermeiden Sie das Angeben der Tags über dem Teil „CREATE/ALTER“ eines Stored Procedure, da das System Probleme hat, das Stored Procedure zu lesen, wenn es in Selligent by Zeta registriert ist.
Zurzeit werden folgende Elemente ausgewählt:
Author
Dies gibt den Autor des ursprünglichen Skripts an.
Beispiel: -- DID - Author: Peggy Heyvaert
CreationDate
Dies sollte das ursprüngliche Erstellungsdatum der Routine enthalten.
Beispiel: -- DID - CreationDate: 2017-02-28
Version
Gibt die Version des Skripts an. Wir folgen dem Versionierungsschema „X.Y.Z“:
- Hauptversionsnummern ändern sich bei einer erheblichen, das heißt großen oder möglicherweise nicht abwärtskompatiblen Änderung an einem Softwarepaket.
- Unterversionsnummern ändern sich, wenn eine neue, kleinere Funktion eingeführt wird oder wenn ein Satz kleinerer Funktionen bereitgestellt wird.
- Patchnummern ändern sich, wenn ein neues Build der Software für Kunden veröffentlicht wird. Dies ist normalerweise bei kleineren Bugfixes oder dergleichen der Fall.
Wenn eine Routine noch nicht in der Produktion verwendet wird, sollte die Hauptversionsnummer „0“ sein. Sobald sie in der Produktion verwendet wird, sollte sie auf mindestens „1“ aktualisiert werden.
Beispiel: -- DID - Version: 1.2.3
Description
Enthält die Beschreibung der Routine. Geben Sie dies so vollständig wie möglich an, damit klar ist, was die Routine tut, ohne dass dafür der Code gelesen werden muss.
Beispiel: -- DID - Description: Funktion, die das erste Zeichen jedes Worts der übergebenen Eingabezeichenfolge groß schreibt.
Exceptions
Wenn die Routine einen spezifischen Fehler oder mehrere melden kann, sollten diese in diesem Element angegeben werden. Wenn von den Anwendungen explizit mehr als ein Fehler ausgegeben wird, sollten diese jeweils auf eine neue Zeile geschrieben werden.
Beispiel:
-- DID - Exceptions: Datensatz nicht gefunden.
-- DID - Exceptions: Datensatz ist bereits abgelaufen.
BusinessRules
In diesem Element sollten alle spezifischen Geschäftsregeln angegeben werden. Sie können mehrere Geschäftsregeln angeben, indem Sie einfach den „DID“-Teil wiederholen. Sie können dies überall in Ihrer Routine verwenden, da dies nicht auf den Header beschränkt ist. Daher sollten Sie dies umfassend verwenden, um verschiedene Teile der Routine zu dokumentieren.
Beispiel:
-- DID - BusinessRules: Prüfen, ob der Datensatz nur einmal in der Liste auftritt.
-- DID - BusinessRules: Prüfen, ob der Datensatz noch aktiv ist.
LastModifiedBy
Dies sollte den Namen der Person enthalten, die die letzte Änderung an der Routine durchgeführt hat.
Beispiel: -- DID - LastModifiedBy: Hermans Oliver
