5 Ways to Improve the Readability of Your ABAP Code Part I. - Using Meaningful Names


Overview

Today, I'm going to start a new series of posts about improving the readability of your code. In this post series, I will share you my top 5 approaches that can help to make your and your colleagues' life easier.

In the past, I have seen many-many ABAP source codes with the lack of readability. These coders usually choose poor names for their programs, classes, methods, subroutines, function modules, variables, and so on, which makes their own and our business more complicated.

I know that in ABAP, we are a bit limited in the length of the identifiers, but usually we have enough characters to express our thoughts (depending on the type of the indentifiers). I don't think it belongs only to these length limitations, I think it's more about your exactitude. Don't be afraid using meaningful names!

Besides the ABAP development, I do many C# development as well thanks to Xamarin and our Website. In the C# community, I have noticed that the coders take more responsibilities for their codes than in ABAP side, they care more about re-usability, transparency, quality, and readability. I believe that this is the way, we should develop in ABAP as well.

Let's take more responsibilities for our codes!


Lazy Style

First of all, I want to show you, how annoying can be an ABAP source code with poor readability. Let's check the following example, and answer the following questions:

  • What is cl_ord1 about?
  • What is its responsibility?
  • What is calc_dp doing?
  • What do ms, tb, and dp mean?

I think these are all hard question for you, if you aren't the implementer of this code (maybe even if you). There are always meetings where the coders are explaining the behavior of their code to the others. I think most of us have been on such a meeting, and we can agree in that they are mostly useless.

What's happen, if we get a code like this below, and our task is to change something in it, because the business logic has been changed. I think most of us starts scratching his/her head, and spends many time to figure out what the code is actually doing before do any changes. It's a waste of time.

My advice is that use meaningful names for your identifiers, and you can avoid these explanation rounds and head scratching!

*----------------------------------------------------------------------*
CLASS cl_ord1 DEFINITION INHERITING FROM cl_ord.
*----------------------------------------------------------------------*
  PUBLIC SECTION.
    ...

  PRIVATE SECTION.
    ...
    METHODS calc_dp
      IMPORTING ms        TYPE string
                tb        TYPE string
      RETURNING value(dp) TYPE i.

ENDCLASS.                    "cl_ord1 DEFINITION

*----------------------------------------------------------------------*
CLASS cl_ord1 IMPLEMENTATION.
*----------------------------------------------------------------------*
  ...
  METHOD calc_dp.
    IF ms = '01' AND tb = 'CH'.
      dp = 30.
    ENDIF.

    IF ms = '09' AND tb = 'TR'.
      dp = 15.
    ENDIF.

    IF ms = '07' AND tb = 'WD'.
      dp = 5.
    ENDIF.
  ENDMETHOD.                    "calc_dp
  ...
ENDCLASS.                    "cl_ord1 IMPLEMENTATION


Use Meaningful Class Names

What if I say that it's a Book Order, and rename the class to cl_book_order, and its base class to cl_order. It's more meaningful for me. We have a base class, cl_order, and many derived classes, like cl_book_order for Books, cl_mobile_order for Mobile devices, or cl_garden_order for Garden equipments. So we apply different business logic for the different type of orders.

*----------------------------------------------------------------------*
CLASS cl_book_order DEFINITION INHERITING FROM cl_order.
*----------------------------------------------------------------------*
  PUBLIC SECTION.
    ...

  PRIVATE SECTION.
    ...
    METHODS calc_dp
      IMPORTING ms        TYPE string
                tb        TYPE string
      RETURNING value(dp) TYPE i.

ENDCLASS.                    "cl_book_order DEFINITION

*----------------------------------------------------------------------*
CLASS cl_book_order IMPLEMENTATION.
*----------------------------------------------------------------------*
  ...
  METHOD calc_dp.
    IF ms = '01' AND tb = 'CH'.
      dp = 30.
    ENDIF.

    IF ms = '09' AND tb = 'TR'.
      dp = 15.
    ENDIF.

    IF ms = '07' AND tb = 'WD'.
      dp = 5.
    ENDIF.
  ENDMETHOD.                    "calc_dp
  ...
ENDCLASS.                    "cl_book_order IMPLEMENTATION


Use Meaningful Method Names

What if I say that the responsibility of our method is to calculate the discount percentage for a book, and rename the method to calculate_discount_percentage. Now, it makes more sense for me, and if someone asks me what that method is doing, I can say that it calculates the discount percentage probably for a book.

*----------------------------------------------------------------------*
CLASS cl_book_order DEFINITION INHERITING FROM cl_order.
*----------------------------------------------------------------------*
  PUBLIC SECTION.
    ...

  PRIVATE SECTION.
    ...
    METHODS calculate_discount_percentage
      IMPORTING ms        TYPE string
                tb        TYPE string
      RETURNING value(dp) TYPE i.

ENDCLASS.                    "cl_book_order DEFINITION

*----------------------------------------------------------------------*
CLASS cl_book_order IMPLEMENTATION.
*----------------------------------------------------------------------*
  ...
  METHOD calculate_discount_percentage.
    IF ms = '01' AND tb = 'CH'.
      dp = 30.
    ENDIF.

    IF ms = '09' AND tb = 'TR'.
      dp = 15.
    ENDIF.

    IF ms = '07' AND tb = 'WD'.
      dp = 5.
    ENDIF.
  ENDMETHOD.                    "calculate_discount_percentage
  ...
ENDCLASS.                    "cl_book_order IMPLEMENTATION


Use Meaningful Parameter Names

What if I say that the method calculate_discount_percentage calculates the discount percentage based on two parameters the month of the sales date and the type of the given book, and rename them to month_of_sales, type_of_book, and discount_percentage.

Now we can easily say that the the discount percentage is calculated in the following way:

  • If the the month of the sales date is 01 and the type of the book is CH, then the discount percentage is 30,
  • If the the month of the sales date is 09 and the type of the book is TR, then the discount percentage is 15,
  • If the the month of the sales date is 07 and the type of the book is WD, then the discount percentage is 5.

We still don't now exactly what the 01, 09, 07, CH, TR, or WD means, but I believe that we got closer to more easily figure out what this code is doing.

*----------------------------------------------------------------------*
CLASS cl_book_order DEFINITION INHERITING FROM cl_order.
*----------------------------------------------------------------------*
  PUBLIC SECTION.
    ...

  PRIVATE SECTION.
    ...
    METHODS calculate_discount_percentage
      IMPORTING month_of_sales             TYPE string
                type_of_book               TYPE string
      RETURNING value(discount_percentage) TYPE i.

ENDCLASS.                    "cl_book_order DEFINITION

*----------------------------------------------------------------------*
CLASS cl_book_order IMPLEMENTATION.
*----------------------------------------------------------------------*
  ...
  METHOD calculate_discount_percentage.
    IF month_of_sales = '01' AND type_of_book = 'CH'.
      discount_percentage = 30.
    ENDIF.

    IF month_of_sales = '09' AND type_of_book = 'TR'.
      discount_percentage = 15.
    ENDIF.

    IF month_of_sales = '07' AND type_of_book = 'WD'.
      discount_percentage = 5.
    ENDIF.
  ENDMETHOD.                    "calculate_discount_percentage
  ...
ENDCLASS.                    "cl_book_order IMPLEMENTATION


Summary

I hope you could experience that it does really matter how do you name your identifiers in your code, whether it's a program, class, method, subroutine, function module, variable or a constant.

Think of your code as a book, your colleagues as readers, and you are the writer who is responsible to write lightweight source code that everyone can easily read and understand.

Of course, this was the first step of improving the readability of our source code, so there are still many ways to improve it. Stay tuned, keep reading! Next, we are going to talk about the magic numbers.


Outlook

If you want to learn more about code best practices in ABAP, then I highly recommend to watch my colleague, Laszlo's Pluralsight course: Introduction to ABAP for SAP Business Warehouse Developers.

At last, take Robert C. Martin's advice, and read his book also (really great article):

blog comments powered by Disqus