Ansicht
Dokumentation

ABENCONTENT_GUIDL - CONTENT GUIDL

Fill RESBD Structure from EBP Component Structure   BAL Application Log Documentation  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Inhalt von Kommentaren

Was in einer Implementierung geschieht, kann sich der Leser in der Regel durch das Studium der ABAP-Anweisungen erschließen. Warum etwas gemacht wird, ist hingegen viel schwerer zu erkennen und erschließt sich häufig erst mühsam in einem viel größeren Kontext.

Sinnvoll kommentieren

Kommentieren Sie Implementierungen so, dass die Kommentare beschreiben, warum etwas gemacht wird, nicht wie.

Im Idealfall dokumentiert sich Quelltext durch die geeignete Wahl von Bezeichnern weitgehend selbst. Dies ist die beste Art, den Aspekt "Was geschieht in diesem Programmabschnitt" zu dokumentieren. Wenn dies der Fall ist, sind zusätzliche Kommentare, die lediglich offensichtliches Verhalten beschreiben, überflüssig und tragen nicht zur Verständlichkeit bei. Darüber hinaus besteht die Gefahr, dass bei Änderungen an der Programmlogik die zugehörigen Kommentare nicht angepasst und dadurch sachlich falsch werden. Dadurch sind solche Kommentare im Folgenden nicht nur nutzlos, sondern sogar irreführend und sollten deshalb von Anfang an vermieden werden.

Umgekehrt neigen Entwickler aber auch häufig dazu, den von ihnen gerade verfassten Quelltext für hinreichend selbstdokumentierend zu halten und verzichten dann auf erklärende Kommentare. Diese Einschätzung ist jedoch allzu oft trügerisch, was spätestens dann offenbar wird, wenn ein Außenstehender versucht, den Quelltext zu verstehen (sei es, um Erweiterungen daran vorzunehmen oder einen Fehler zu identifizieren). Oft steht sogar der Autor selbst vor diesem Problem, wenn er nach längerer Pause erneut mit dem von ihm verfassten Quelltext konfrontiert wird.

Selbst wenn die Bezeichner so gewählt sind, dass ein Leser leicht nachvollziehen kann, was geschieht, fehlt häufig das Warum. Daher müssen diese Informationen in Form von Kommentaren im Quelltext hinterlegt werden. Dies schließt auch eine Beschreibung verwendeter Algorithmen oder zumindest deren Nennung ein.

Hinweis

Wir sprechen hier hauptsächlich von der Kommentierung der Implementierung von Funktionalität. Eine andere Rolle spielen Kopfkommentare. Solche Kommentare, die in der Regel als über Sternchen (*) eingeleitete Zeilenkommentare auftreten, unterteilen große Quelltexte in sinnvolle Abschnitte und können administrative Einträge enthalten. Aber auch für diese gilt, dass sie nicht wiederholen sollen, was durch den Quelltext oder auf sonstige Weise klar erläutert wird. Beispielsweise sind der letzte Änderer oder das Änderungsdatum eines Programms in dessen Programmeigenschaften sichtbar. Auch ein Kopfkommentar mit dem Namen einer Klasse oder Methode direkt über der Klasse oder Methode ist redundante Information. Sinnvoller ist dagegen die Abgrenzung logischer Programmteile, die nicht im Code ausdrückbar ist, wie beispielsweise die Aufteilung eines Programms in einen globalen Deklarationsteil und einen Implementierungsteil. Dies ist in der Regel auch nur notwendig, wenn diese Einteilung nicht durch Include-Programme geschieht.

Folgender Quelltext zeigt Kommentare, deren Aussage auch durch die kommentierten Anweisungen ersichtlich ist.

"Select udat, stime from trdir
"into change_date, change_time
SELECT SINGLE udat, stime
       FROM trdir
       WHERE name = @prog_name
       INTO (@change_date, @change_time).

"Set version_date, version_time to change_date, change_time
IF sy-subrc = 0.
   IF change_date > version_date.
      version_date = change_date.
      version_time = change_time.
   ELSEIF change_date = version_date AND
          change_time > version_time.
   version_time = change_time.
  ENDIF.
ENDIF.

Folgender Quelltext ersetzt die Kommentare aus obigem Beispiel durch eine Beschreibung, warum etwas geschieht.

"If a newer program exists, version time stamp must
"be adjusted to program time stamp
SELECT SINGLE udat, stime
       FROM trdir
       WHERE name = @prog_name
       INTO (@change_date, @change_time).

IF sy-subrc = 0.
   IF change_date > version_date.
      version_date = change_date.
      version_time = change_time.
   ELSEIF change_date = version_date AND
          change_time > version_time.
   version_time = change_time.
  ENDIF.
ENDIF.

CL_GUI_FRONTEND_SERVICES - Frontend Services   CL_GUI_FRONTEND_SERVICES - Frontend Services  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Length: 5567 Date: 20240523 Time: 155707     sap01-206 ( 104 ms )