ADT, ABAP Doc, abapGit, GitHub, Markdown, mermaid

Dear community, the title of this blog sounds like buzzword bingo, but it isn’t. The technologies that these terms represent can be used in combination to keep track of things in everyday developer work. How? That’s what this blog is about.

At the moment the whole thing is still research, trying out and gaining experience. Please feel free to share your experiences.

ABAP Development Tools

ABAP Development Tools (ADT) is the development environment for ABAP recommended by SAP. You can use it to develop for on-premises, but especially for cloud systems such as the Business Technology Platform (BTP).

From the beginning, the ADT relied heavily on text-based working with development artifacts. The ABAP Workench and other transactions in the SAP GUI, on the other hand, often rely on form-based working with development artifacts.

As an example, the creation of a function module can be compared. The interface is plain text in the ADT, in the ABAP Workbench there are different tabs for IMPORTING, EXPORTING, CHANGING, TABLES and EXCEPTIONS.

Both approaches, text-based and form-based editing, have their strengths and weaknesses. It took me some time to get used to text-based editing 🙄 Meanwhile, I find the idea “everything is text” very nice. But that may also be because I’ve become a big fan of Markdown.

Regardless, for our example here, the ADT as development environment is the method of choice.

ABAP Doc

The ABAP Doc documentation has a nice definition of what ABAP Doc is:

“ABAP Doc allows declarations in ABAP programs to be documented, based on special ABAP Doc comments. ABAP development environments that support ABAP Doc, such as ABAP Development Tools (ADT), analyze the content of ABAP Doc comments, convert it to HTML and display it appropriately.“

This is a great chance to make development artifacts easier to understand with comments that are also specially handled by our development environment ADT. Just take a look at the ABAP Doc documentation to see what is possible.

I can only recommend using ABAP Doc sparingly and purposefully. Otherwise there is a confusing mix of ABAP Doc comments and ABAP instructions.

The knowledge should result from the design of the development artifacts and their interaction. Please note the recommendations from Clean ABAP style guide.

Below are two very simple examples of ABAP Doc comments that describes classes:

"! Class to represent a building as an object.
CLASS zmke_cl_building DEFINITION PUBLIC FINAL CREATE PUBLIC.
...

"! Class to represent a room as an object.
CLASS zmke_cl_room DEFINITION PUBLIC FINAL CREATE PUBLIC.
...

If you create an object of these classes and use the element information (F2 key) on the object, you get for example this documentation:

abapGit and GitHub

abapGit allows us to use the strengths of Git in the ABAP world as well. In particular, we can transfer our development artifacts from the repository of the respective SAP system (SAP ERP, SAP BTP and so on) to a central repository, for example on GitHub. This brings us much closer to the idea of an independent, decentralized, non-linear and temporally decoupled development.

At this point I would like to say thanks to developers like Lars Hvam and Christian Guenter and all the not mentioned but not forgotten ABAP developers who made abapGit possible and thus provided one of the essential foundations for open source to flourish in the ABAP environment 🙏.

Back to the example: The ZMKE_CL_BUILDING class shown above is a development artifact. If it is transferred to a repository on GitHub with abapGit, its source code can be found (and edited) there. So also the included ABAP Doc comments.

Markdown on GitHub

Wikipedia’s definition puts it beautifully: “Markdown is a lightweight markup language for creating formatted text using a plain-text editor“. GitHub offers us an incredible number of helpful documentation options within our repository via Markdown.

Simply create *.md files as readme.md is and follows the thought “everything is text”. After editing, which is possible directly on GitHub, GitHub takes care of the visually appealing preparation in HTML.

So here’s a link for learning Markdown and check this link and this one to see how GitHub make use of Markdown.

mermaid

Here’s the definition of mermaid from their website: “Mermaid lets you create diagrams and visualizations using text and code. It is a Javascript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.”

With mermaid we can, for example, create class diagrams using a syntax easy as Markdown is. Even better: GitHub supports exactly that and prepares such a class diagram optically and in place.

Here’s our example as very simple mermaid class diagram on GitHub in plain text:

```mermaid
classDiagram
    ZMKE_CL_BUILDING *-- ZMKE_CL_ROOM
    
    class ZMKE_CL_BUILDING{
          -building_number
    }
    
    class ZMKE_CL_ROOM{
          -room_number
          +get_room_setup()
    }    
    
    click ZMKE_CL_BUILDING href "https://github.com/Keller-Michael/class_model_example/blob/main/src/zmke_cl_building.clas.abap" 
    click ZMKE_CL_ROOM href "https://github.com/Keller-Michael/class_model_example/blob/main/src/zmke_cl_room.clas.abap"
```   

And here’s the output, rendered by GitHub:

It’s interesting that you can set a link for each class, linking on files in your repository or somewhere else. So it can refer directly to the appropriate file with the source code of the class, for example. This allows you to look at the class diagram and jump into the appropriate source code on GitHub.

For that reason, I wouldn’t put much effort into the class diagram at first. It’s only intended to show the connections. By linking to the development artifacts, you can reach them easily and look at the details there. As a side note, the link path should be relative to the repository. But I haven’t gotten that resolved yet.

Conclusion

By using ABAP Doc, for example for a brief description of classes, in connection with the ADT, a simple but easily accessible documentation can be created. If you make the documented development artifacts available on GitHub and create a simple mermaid class diagram, it’s easy for other developers to get started with your source code because they have a fast overview. Even withouth access to a SAP development system.

Automatic generation of the mermaid class diagram on a commit would of course be ideal, or at least one could generate a class diagram in the ADT.

Thanks for reading, stay healthy and kind regards

Michael