practical use of ABAP Doc in legacy code

Dear community, lately I’ve been searching for practical use cases with ABAP Doc. I think I’ve found one in connection with legacy code. That’s what today’s blog is about. And of course your opinion on it: Helpful or not?

Ok, let’s start. Has anyone ever seen such lines? Or even written yourself 😉

TYPES t_t_type TYPE STANDARD TABLE OF T000.

CONSTANTS c_i TYPE p LENGTH 8 DECIMALS 14 VALUE '3.14159265358979'.
CONSTANTS x TYPE c LENGTH 1 VALUE 'X'.
CONSTANTS con_np TYPE REF TO object VALUE IS INITIAL.

DATA g_dmbtr TYPE dmbtr.
DATA gv_x TYPE char1.

DATA: lt_result TYPE t_t_type,
      wa LIKE LINE OF lt_result.

Unfortunately you can find something like that quite easily. Often in legacy code. A good place to start your search is the TOP include of report/function group or some often implemented user exits like MV45A. For more examples of hard to understand lines check the ABAP gore coffee corner discussion.

What’s the problem with these lines? The names say nothing or are even confusing. This is the opposite of what Clean ABAP recommends with regard to naming. A real, lost opportunity to simply incorporate additional information in the source code 🙁 This is what it can look like during an analysis.

element information during an analysis

Unfortunately, legacy code has normally some more disadvantages. Without a thorough understanding (runtime analysis) and appropriate test data, you would rather not make any changes. Don’t even change a data type, variable or constant name unless you are very brave, like gambling or are otherwise very willing to take risks 😉

How can you create now some informative value without risk? ABAP Doc allows us to describe data types, variables and constants using suitable ABAP Doc comments. In connection with the ABAP Development Tools and the element information (F2 key) you can display this documentation at any time when data type, variable or constant is used in the source code. This helps during the analysis of the source code a lot.

Another good point: Adding ABAP Doc comments has very little effect on the source code. The source code gets bigger, but that’s all. ABAP Doc comments are no ABAP instructions 🙂

How could our lines now look like with ABAP Doc comments?

"! table type for client customizing
TYPES t_t_type TYPE STANDARD TABLE OF T000.

"! number Pi
CONSTANTS c_i TYPE p LENGTH 8 DECIMALS 14 VALUE '3.14159265358979'.

"! used like abap_true
CONSTANTS x TYPE c LENGTH 1 VALUE 'X'.

"! null pointer 
CONSTANTS con_np TYPE REF TO object VALUE IS INITIAL.

"! amount in local currency
DATA g_dmbtr TYPE dmbtr.

"! test switch, <strong>clear to write to database</strong>
DATA gv_x TYPE char1.

"! table with client customizing
DATA: lt_result TYPE t_t_type,
      "! line of table lt_result (client customizing)
      wa LIKE LINE OF lt_result.

And here the view of our example via ADT element information.

element information with ABAP Doc comment

Ok, I admit the Boolean example is simple. However, you can also include more information in an ABAP Doc comment. Here’s an example, not so obvious.

more information to transport via ABAP Doc comment

That’s all for today. What do you think?

Best regards, thanks for reading and stay healthy

Michael

P. S.: Not tired of reading? Check this blog.