Skip to content

ABAP Keyword Documentation →  ABAP Programming Guidelines →  Structure and Style →  Comments 

Arrangement in the Source Code

Other versions: 7.31 | 7.40 | 7.54

Background

The arrangement of comments plays an important role (in addition to comment language and comment content) in making programs easy to read.

Rule

Arrange comments correctly

Place comments in front of the statements that they describe. The horizontal arrangement of comments should follow the indentations of the source code. End of line comments should only be placed after declarative or concluding statements.

Details

Vertical positioning

For control structures, this means that comment lines directly before a control statement (such as IF or WHILE) refer to the associated condition and comment lines after the control statement refer to the associated statement block. Comment lines directly before an ELSE or WHEN OTHERS statement have obviously been put in the wrong place.

End of line comments

Therefore, you should make comments for entire statement blocks. Use self-contained comment lines to do this. This is because it is difficult to describe a reference to more than one statement line if you use end of line comments.

End of line comments are suitable for the following situations:

  • To comment on declarative statements
  • To indicate block ends (separate from indentations) in larger control structures
  • To justify pseudo comments (at the relevant places) for hiding messages from the extended program check or Code Inspector.

The pseudo comments for hiding warnings of the extended program check and the Code Inspector play a special role. They are not comments in the usual sense of the word. They are program directives that must be appear in the same lines as the commented statements to take full effect. These pseudo comments were replaced by pragmas for the extended program check.

Indentations

These indentations can only be achieved using comments that start with a quotation mark ("), because this character can be in any position. A comment line that starts with an asterisk (*) must always be in the first position. It is therefore strongly recommended that you start all comments used in procedures (methods) with a quotation mark and the correct indentation. Comment lines that start with a quotation mark must not be confused with end of line comments, which are appear after different code.

Comment lines that start with an asterisk should only be used for head comments of classes and procedures. Here they help to subdivide a source code into logical sections. In addition, they are useful for temporarily disabling statements by commenting them out. The commented-out code can be clearly distinguished from actually indented comments.

Bad example

The following source code shows the implementation part of a class. The positioning of the comments does not follow the above rule.

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.

Good example

The following source code shows the same implementation part as above. However, the comments are positioned as recommended. Comment lines that start with an asterisk (*) are used as header comments in the program structure. End of line comments only appear after declarations and block ends. All other comments appear in comment lines before the described statements and are indented accordingly.

*----------------------------------------------------------*
* 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