Ansicht
Dokumentation

ABENARRANGE_GUIDL - ARRANGE GUIDL

Addresses (Business Address Services)   PERFORM Short Reference  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Anordnung im Quelltext

Neben Kommentarsprache und Kommentarinhalt spielt auch die Anordnung der Kommentare eine wichtige Rolle für die Lesbarkeit eines Programms.

Kommentare richtig anordnen

Platzieren Sie Kommentare vor den Anweisungen, die sie beschreiben. Die horizontale Anordnung von Kommentaren soll den Einrückungen des Quelltextes folgen. Zeilenendekommentare dürfen nur hinter deklarativen oder blockabschließenden Anweisungen angebracht werden.

Vertikale Positionierung
Im Allgemeinen wird beim Durchlesen eines Quelltextes bevorzugt, zunächst den Kommentar und danach die beschriebenen Anweisungen zu sehen. Bei dieser Anordnung wird der Zusammenhang zwischen Kommentar und zugehöriger Quelltextpassage intuitiv klar.

Für Kontrollstrukturen folgt daraus, dass sich Kommentarzeilen unmittelbar vor einer Kontrollanweisung (beispielsweise IF oder WHILE) auf die zugehörige Bedingung und Kommentarzeilen nach der Kontrollanweisung auf den zugehörigen Anweisungsblock beziehen. Kommentarzeilen unmittelbar vor einer Anweisung ELSE oder WHEN OTHERS sind daher offensichtlich falsch platziert.

Zeilenendekommentare
Diese Kommentare sind im Zusammenhang mit ausführbaren Anweisungen problematisch. Einzelne ausführbare Programmzeilen sind im Allgemeinen nicht so komplex, dass sie einen eigenen Kommentar rechtfertigen würden. Werden hier dennoch Zeilenendekommentare angehängt, handelt es sich häufig um unerwünschte Wiederholungen dessen, was die Anweisungen selbst auch schon hinreichend deutlich zu erkennen geben. Darüber hinaus tendieren sie zu kryptischem Inhalt, da das Zeilenende meist zu wenig Platz für aussagekräftige Kommentare bietet. Eine einheitliche Ausrichtung solcher Zeilenendekommentare ist nur mit hohem Aufwand zu erreichen.

Aus diesen Gründen sollen ganze Blöcke von Anweisungen kommentiert werden. Hierfür werden frei stehende Kommentarzeilen verwendet, da mit Zeilenendekommentaren der Bezug zu mehr als einer Anweisungszeile schwer auszudrücken ist.

Zeilenendekommentare können in folgenden Situationen sinnvoll verwendet werden:

• um deklarative Anweisungen zu kommentieren

• um Blockenden in größeren Kontrollstrukturen zusätzlich zur Einrückung zu kennzeichnen

• um Pseudokommentare zur Ausblendung von Meldungen der erweiterten Programmprüfung oder des Code Inspectors an Ort und Stelle zu rechtfertigen.

Die Pseudokommentare zum Ausblenden von Warnungen des Code Inspectors spielen eine besondere Rolle. Dies sind keine Kommentare im herkömmlichen Sinn, sondern Programmdirektiven, die in denselben Zeilen wie die kommentierten Anweisungen stehen müssen, um ihre Wirkung zu entfalten. Diese Pseudokommentare wurden für die erweiterte Programmprüfung durch Pragmas abgelöst.

Einrückungen
Die Formatierung von Quelltext durch Einrückungen ist für die Nachvollziehbarkeit seiner logischen Struktur durch einen menschlichen Leser essenziell und wird von Regel zur Verwendung des Pretty Printers gefordert. Werden jedoch Kommentare in den Quelltext eingestreut, die dieser Formatierung nicht folgen, verdecken sie die logische Struktur und beeinträchtigen die Lesbarkeit. Kommentarzeilen müssen daher die gleiche Einrückung aufweisen wie die Anweisungszeilen, auf die sie sich beziehen.

Diese Einrückungen sind nur mittels der durch ein Anführungszeichen (") eingeleiteten Kommentare zu erreichen, da dieses an einer beliebigen Position stehen kann. Bei einer durch einen Stern (*) eingeleiteten Kommentarzeile muss dieser immer an der ersten Stelle stehen. Wir empfehlen daher ausdrücklich, alle Kommentare innerhalb von Prozeduren (Methoden) stets mit einem Anführungszeichen mit der richtigen Einrückung einzuleiten. Kommentarzeilen, die mit einem Anführungszeichen eingeleitet werden, sind nicht mit Zeilenendekommentaren zu verwechseln, die hinter anderem Code stehen.

Durch einen Stern eingeleitete Kommentarzeilen sollen nur für Kopfkommentare von Klassen und Prozeduren verwendet werden, wobei sie helfen, einen Quelltext in logische Abschnitte zu unterteilen. Darüber hinaus eignen sie sich dazu, Anweisungen durch Auskommentierung temporär unwirksam zu machen, weil sich der auskommentierte Code dann deutlich von echten eingerückten Kommentaren abhebt.

Folgender Quelltext zeigt den Implementierungsteil einer Klasse mit Kommentaren, deren Positionierung nicht obiger Regel folgt.

CLASS application IMPLEMENTATION. "Application class
  METHOD main. "Main Method

* Item data
  DATA items  TYPE STANDARD TABLE
              OF REF TO item.
DATA item_ref LIKE LINE OF items.

* Amount data
  DATA amount TYPE i.
  DATA total_amount TYPE i.
  ...

* Loop over all items to compute total amount
    LOOP AT items INTO item_ref. "Loop over all items
      IF item_ref IS BOUND AND
         item_ref->is_valid( ) = abap_true. "Check validity
         amount = item_ref->get_amount( ). "Get amount
         ADD amount TO total_amount. "Add amount to totals
          ...                                          "...
       ELSE.
          ...
      ENDIF.
    ENDLOOP.
    ...
  ENDMETHOD.
ENDCLASS.

Folgender Quelltext zeigt den gleichen Implementierungsteil wie obiges Beispiel, wobei die Kommentare jedoch gemäß der Empfehlung gesetzt sind. Mit einem Stern(*) eingeleitete Kommentarzeilen dienen als Kopfkommentare der Strukturierung des Programms. Zeilenendekommentare kommen nur hinter Deklarationen und Blockenden vor. Alle sonstigen Kommentare stehen in Kommentarzeilen vor den beschriebenen Anweisungen und sind entsprechend eingerückt.

*----------------------------------------------------------*
* Class implementations
*
*----------------------------------------------------------*

CLASS application IMPLEMENTATION.

*----------------------------------------------------------*
  METHOD main.
     DATA: items    TYPE STANDARD TABLE
                    OF REF TO item,     "Item table
           item_ref LIKE LINE OF items. "Item reference
     DATA: amount TYPE i, "Amount per item
           total_amount TYPE i. "Total amount of items
...

"Loop over all items to compute total amount
LOOP AT items INTO item_ref.
  IF item_ref IS BOUND AND
     item_ref->is_valid( ) = abap_true.
     "Compute total amount for valid items
     amount = item_ref->get_amount( ).
     ADD amount TO total_amount.
     ...
  ELSE.
  ENDIF. "item_ref IS BOUND AND...
ENDLOOP.
...
ENDMETHOD. "main
*----------------------------------------------------------*
ENDCLASS. "application

rdisp/max_wprun_time - Maximum work process run time   SUBST_MERGE_LIST - merge external lists to one complete list with #if... logic for R3up  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Length: 9174 Date: 20240523 Time: 155148     sap01-206 ( 128 ms )