5 Ways to Improve the Readability of Your ABAP Code Part IV. - Formatting Does Matter


Overview

First of all Happy and Successful New Year to my dear readers! I hope you all had a great holiday with your family, could relax a bit, and you are ready to improve further our ABAP coding style.

I skipped two weeks of writting posts, because I didn't want to bother you with boring ABAP codes during the holidays, but today we are going to continue our work. Let me refresh what we learn until now!

In the previous posts we talked about using meaningful identifier names, why to avoid magic numbers, and the benefits of organizing our code with functions. As you have experienced, these methods require more time to invest (choosing the best identifier name, how to structure the code with functions, and so on), but at the end it pays off multiple times.

Today I want to share you a very trivial and easy method that requires less work than these methods above, but results a more readable code than before, this method called Formatting.

The focus again on helping your readers to understand your code easier, and saving time for them!


Lack of formatting

It can happen that you use meaningful names for your identifiers, avoid magic numbers, and organizing your code with functions, but your code is still unreadable.

The problem can be that the code doesn't follow any pattern or alignment rule, so during reading your eyes goes slapdash and it strains your brain. As a result, it makes harder to understand the purpose of the code.

Use any kind of formatting pattern that is good for you, the point is, readability and formatting are friends, don't forget it!

...
START-OF-SELECTION.
CALL FUNCTION 'GUI_UPLOAD'
EXPORTING
  filename = 'C:\customers_with_attribute.xml'
TABLES
  data_tab = xml_content.



PERFORM convert_to_flat_string USING    xml_content
CHANGING xml_content_flat.


CALL TRANSFORMATION zcustomer_st 
SOURCE XML xml_content_flat

RESULT customers = customers.
INSERT  zcustomer FROM TABLE customers.

*&---------------------------------------------------------------------*
FORM convert_to_flat_string USING    xml_content      TYPE string_tt
CHANGING xml_content_flat TYPE string.
*&---------------------------------------------------------------------*

  DATA xml_line LIKE LINE OF xml_content.
  LOOP AT xml_content INTO xml_line.
    CONCATENATE xml_content_flat
    xml_line
    INTO xml_content_flat.
  ENDLOOP.
ENDFORM.
...


Using Pretty Printer

When we talk about code formatting in ABAP, the first idea should be the built-in function, called Pretty Printer. It's a good tool, but not completely perfect (you have the chance to enhance the standard behavior). It can do the followings (depending on the settings):

  • indents the statements creating a structured, hierarchical source code,
  • inserts standard comments,
  • make lowercase the complete source code,
  • make uppercase the complete source code,
  • make lowercase the keywords,
  • make uppercase the keywords.

It brings us closer to our goal (getting readable code), but the code still reflects poor readability. Using the tool, Pretty Printer we got our statements as indented (for example the CALL FUNCTION method is well-formatted), it's alright, but what about the PERFORM statement?

...
START-OF-SELECTION.
  CALL FUNCTION 'GUI_UPLOAD'
    EXPORTING
      filename = 'C:\customers_with_attribute.xml'
    TABLES
      data_tab = xml_content.



  PERFORM convert_to_flat_string USING    xml_content
  CHANGING xml_content_flat.


  CALL TRANSFORMATION zcustomer_st
  SOURCE XML xml_content_flat

  RESULT customers = customers.
  INSERT  zcustomer FROM TABLE customers.

*&---------------------------------------------------------------------*
FORM convert_to_flat_string USING    xml_content      TYPE string_tt
CHANGING xml_content_flat TYPE string.
*&---------------------------------------------------------------------*

  DATA xml_line LIKE LINE OF xml_content.
  LOOP AT xml_content INTO xml_line.
    CONCATENATE xml_content_flat
    xml_line
    INTO xml_content_flat.
  ENDLOOP.
ENDFORM.                    "convert_to_flat_string
...


Think about your code as a book

As you remember, I have used this phrase many times in my posts. The reason for this, I believe that our code is a book for other developers who wants/has to read it, so it does really matter how do we write it.

During writing this post, I have flipped through one of my favorite books, called

I really like this book because it's easy to read for non-designers also, and it explains the basic design principles to the readers in a very practical way. It gives you a brief introduction to the world of designers that you can use to write more readable codes than ever. The main point of the book are the four design principles.

Keep the four design principles in your mind: Alignment, Proximity, Repetition, and Contrast (it will be detailed in the next post)! In this post, we are going through on these principles, and I demonstrate how I apply them in my ABAP coding.


Alignment

Beside line indents, I also apply alignments for the individual words, for example I always align the USING, CHANGING clause of the PERFORM statements, in order to get much more readable code. The CONCATENATE statement is in the same category, because you can write it into one line, or break them into separate lines, and align them to get a more self-expressive code: CONCATENATE the strings xml_content_flat and xml_line together INTO the xml_content_flat.

It doesn't matter you prefer writing one line statements or breaking them into separate line, the point is pay attention to the readability.

What Robin Williams says about alignment is that every item on a screen, or a sheet of paper should be aligned to other items, creating a connection between them, and make them logically connected together.

Do you have any idea, why did we use many blank lines between the CALL FUNCTION and PERFORM statements, or the RESULT clause is part of the CALL TRANSFORMATION, or not? At this stage our code still gives us too much headache while reading it, the problem lies in the distances between the lines.

...
START-OF-SELECTION.
  CALL FUNCTION 'GUI_UPLOAD'
    EXPORTING
      filename = 'C:\customers_with_attribute.xml'
    TABLES
      data_tab = xml_content.



  PERFORM convert_to_flat_string USING    xml_content
                                 CHANGING xml_content_flat.


  CALL TRANSFORMATION zcustomer_st
    SOURCE XML xml_content_flat

    RESULT customers = customers.
  INSERT zcustomer FROM TABLE customers.

*&---------------------------------------------------------------------*
FORM convert_to_flat_string USING    xml_content      TYPE string_tt
                            CHANGING xml_content_flat TYPE string.
*&---------------------------------------------------------------------*

  DATA xml_line LIKE LINE OF xml_content.
  LOOP AT xml_content INTO xml_line.
    CONCATENATE xml_content_flat
                xml_line
           INTO xml_content_flat.
  ENDLOOP.
ENDFORM.                    "convert_to_flat_string
...


Proximity

Proximity is a tool in your tool-set the express in another way the connection between different items. The rule is put relevant items closer to each other, and place them farther from each other if they are not relevant to each other.

For example the CALL TRANSFORMATION statement consists of the SOURCE XML and RESULT clauses, so it's important to place them closer to each other to express they belong to each other. But there is nothing to do with the INSERT statement, so it should be separated from it with blank lines.

What now? Is it more readable? Yes, I think it's more readable than before, it gives you the feeling it's a structured code that follows some kind of alignment pattern.

...
START-OF-SELECTION.
  CALL FUNCTION 'GUI_UPLOAD'
    EXPORTING
      filename = 'C:\customers_with_attribute.xml'
    TABLES
      data_tab = xml_content.

  PERFORM convert_to_flat_string USING    xml_content
                                 CHANGING xml_content_flat.

  CALL TRANSFORMATION zcustomer_st
    SOURCE XML xml_content_flat
    RESULT customers = customers.
  
  INSERT zcustomer FROM TABLE customers.

*&---------------------------------------------------------------------*
FORM convert_to_flat_string USING    xml_content      TYPE string_tt
                            CHANGING xml_content_flat TYPE string.
*&---------------------------------------------------------------------*
  DATA xml_line LIKE LINE OF xml_content.
  
  LOOP AT xml_content INTO xml_line.
    CONCATENATE xml_content_flat
                xml_line
           INTO xml_content_flat.
  ENDLOOP.
ENDFORM.                    "convert_to_flat_string
...


Repetition

A repetition is a bit different from the others above, it says that you should follow a chosen formatting strategy and apply it consequently in the complete source code, and other code also.

The concept is the following: if you apply the same formatting strategy from function to function, from data declaration to data declaration, and so on, you are going to help your readers, because they get used to your coding style quickly, and from line to line understand your code easier without any headache. That's the power of repetition!

Choose a style and apply it consequently!


Summary

I hope you got the feeling of well-formatted code, and see the benefits of using a consequent formatting style. I know it sounds a bit unnecessary and time-wasting effort, but believe me, later when you come back to your code to modify, you are going to thank to yourself that you spent a bit more time on formatting your code.

Stay tuned, keep reading! If you want to get notification about the newest posts, follow me or subscribe to our newsletter!

If you liked it, please share it! Thanks!

blog comments powered by Disqus