find names for classes and methods
Thanks to the “Clean ABAP” style guide I think a lot more about the maintainability of my source code. A particularly important point in this context is readability.
In the style guide many recommendations are made to improve the readability. It’s about the order and the combination, how many statements you should place in one line and more. And there is a recommendation to use descriptive names.
I find the topic very important. It can be easy to follow the idea of an application or difficult. That often depends on the terms.
In contrast to the ABAP syntax, the names of variables, classes and methods are “only” limited in length, the permitted characters and their permitted position. How they are finally called decides the developer. Hence many names and term combinations quickly emerge and they must be understood in the overall context of the application.
The following is a small example to illustrate the impact of class and method names on readability. It’s designed under “laboratory condition“. Here are some key points:
- A report is needed that displays sales orders from the Sales and Distribution module (SD) as list.
- The list should be displayed by ABAP List Viewer (ALV).
- At the moment there are just a few fields from table VBAK needed.
- Classes and methods should have English names.
Technically, that can be solved in different ways. For example with ABAP Core Data Services (CDS) and CDS based ALV or with SELECT-statement on tables and “classic” ALV (object-oriented or function module REUSE_ALV_GRID_DISPLAY_LVC) or a mix. For the example we use SELECT-statement on table VBAK and “classic” ALV.
We develop a single class called ZCL_LIST with two methods called SELECT and SHOW. All source code is implemented in this class.
What should I say? The names of the class and the methods reveal almost nothing about the context.
How to do it better? According to the style guide, it is recommended to choose terms from the solution domain or problem domain. In our example, business terms increase readability. Here are some ideas how to find them:
- Check the concept if it’s available. The terms used there can be good clues.
- Check help.sap.com.
- If you identify one or more business object types that belongs to your development, try transaction BAPI. Check the terms that are used in the associated documentation, function modules and descriptions.
- Try SAPterm via transaction STERM or online.
- If you identify one or more important tables/data types, check the documentation in English.
- If you identify an important data element, check the default component name.
- Log in with Language “EN” (English) instead of your native language. Then open the business transaction you know from your daily work and check the terms.
Now with terms from the solution domain equipped we can choose a different approach. We develop a class named ZCL_SALES_ORDERS_LIST with two methods called SELECT_SALES_ORDERS and SHOW_ALV.
That’s already more informative. Also conceivable would be SELECT_SALES_ORDERS_FROM_DB or READ_SALES_ORDERS or READ_SALES_ORDERS_FROM_DB.
The first and second approaches violate the “separation of concerns (SoC)” design principle because our class ZCL_SALES_ORDERS_LIST has too many tasks like reading from database table and displaying data.
That may be ok for a small report. But if new requirements/features are added, we quickly create an inflexible monolith. In my experience, these requirements arise very fast. Especially if the list is used productively 😉 To avoid the creation of a monolith, we could use three classes:
- ZCL_SALES_ORDERS_PROVIDER (or ZCL_SALES_ORDERS_READER)
The class ZCL_SALES_ORDERS_LIST uses the class ZCL_SALES_ORDERS_PROVIDER to select the sales orders and then outputs them via class ZCL_SALES_ORDERS_ALV. Interestingly enough, the use of specialized classes also has the advantage that the class name becomes more expressive and thus contributes more to understanding.
If we previously had ZCL_SALES_ORDERS_LIST->SELECT_SALES_ORDERS, we can now avoid repeating the term SALES_ORDERS in the method name. So we get ZCL_SALES_ORDERS_PROVIDER->SELECT.
I would prefer the name SELECT if we use the JOIN addition with our SELECT-statement to read header and position data of sales orders at once. Something like SELECT_HEADERS_AND_POSITIONS is certainly ok, too.
Otherwise, specialized methods such as READ_HEADER or READ_POSITIONS are recommended. Perhaps with an addition like FROM_DB.
Ok, that’s all for now – these were some thoughts on the subject of class and method names. As already described, there are countless approaches. What do you think about?
Best regards and thanks for reading