Best Practice Leitfaden Development - DSAG

6.2 doKuMentation Von entWiCKLunGsoBJeKten
neben Methoden, Funktionsbausteinen und reports, die dokumentation im Quelltext enthalten
können, existieren weitere entwicklungsobjekte im aBaP-system, die keinen Quelltext beinhalten
und daher auf anderem Weg dokumentiert werden müssen. Beispiele dafür sind:
> interfaces
> ddiC-objekte
> transaktionen
BEST PRACTICE: Wir empfehlen, für alle entwicklungsobjekte, unabhängig von Quelltexten, die
Möglichkeiten zur dokumentation der aBaP Workbench zu nutzen und die aufgaben und
Bedeutungen dieser objekte im saP-system zu dokumentieren. im Vergleich zur dokumentation
im Quelltext ist hier der Änderungsverlauf nicht im Vordergrund, sondern der ist-stand sollte hier
dargelegt werden.
da die dokumentation auch an das transportwesen angeschlossen ist, steht diese dokumentation
in allen stages einer systemlandschaft zur Verfügung. Weiterhin kann die dokumentation von allen
Benutzern eingesehen werden und wird in einigen Fällen (reports) vom aBaP-system automatisch
in die Benutzungsoberfläche eingebunden. ein weiterer Vorteil besteht darin, dass diese dokumentation
übersetzbar ist.
6.3 doKuMentation iM QueLLtext
6.3.1 dokumentation und Kommentierung von anweisungen/anweisungsblöcken
Generell sollten anweisungsblöcke im Quelltext (kurz) kommentiert werden, damit ein schnelles
zurechtfinden in fremden Programmen ermöglicht wird. dabei soll in einer Kommentarzeile kurz
beschrieben werden, welche aufgabe der nächste anweisungsblock hat. dokumentieren sie
insbesondere, warum sie etwas machen, nicht wie. dabei gilt der Grundsatz: so wenig Kommentar
wie möglich, so viel Kommentar wie nötig. Vermeiden sie daher redundante informationen (wie
name des dokumentierten Moduls, den letzten Änderer etc).
BEST PRACTICE: als Kommentierungssprache sollte englisch verwendet werden. entwicklungsteams
arbeiten heutzutage überwiegend international zusammen. auch wenn sie derzeit rein
deutschsprachig entwickeln, kann ihr Projekt im Laufe der zeit internationalisiert werden. der
aufwand, der dann durch Koordinationsprobleme oder sogar nachträgliches Übersetzen entsteht,
steht in keinem Verhältnis zu dem vielleicht größeren aufwand durch englische dokumentation.
es hat sich außerdem gezeigt, dass die Lesbarkeit von Code und Kommentaren besser ist, wenn
die Kommentare englisch sind. denn die aBaP-Befehle selbst sind englisch und im stil von sätzen
aufgebaut. der Leser muss bei englischer dokumentation also nicht ständig beim Lesen des
Quelltextes die sprache wechseln.
35
Best Practice Leitfaden deveLoPment, 31. Januar 2013, © dsaG e. v.