Legacy Code – Storing the mental model in diagrams

This post is inspired by a talk by Tudor Girba at the the SAP Inside Track Munich 2015 “Solving real problems without reading code”. Thanks for all community members for their work and a special thank to Damir Majer for inviting Tudor Girba.

There is a famous cartoon by Jason Heeris Why you shouldn’t interrupt a programmer

After the coffee break of his colleague, the mental model of the developer is gone. So we may ask: “Can we materialize the mental model”. Or at least a significant part of it. So that the disaster is not so big, so that something remains that helps the developer to rebuild his mental model.

The first technique is to draw models while coding. I did this quite often. But it is time consuming. After some time the drawing becomes incorrect and has to be corrected. This added to the cognitive stress that was already present due to my work on the coding. So I did this sometimes, but not very often. And when I did it, I often questioned whether it was worth the effort.

Drawing UML diagrams became easier after I learned from plantUML. Diagrams in plantUML are made from texts, these texts are easier to make and change. This saved a lot of time. But when I worked with real code I needed very often informations about the usage of attributes and methods by other methods. This is not possible with UML class diagrams. So I mapped Methods to classes, and classes to packages; that worked somehow, but not very well.

There are tools to extract model informations from an SAP system. The UML class diagram is in newer releases now working very well. But it may require a correct setup of the SAPGui. For this there exists projects to extract UML class diagrams to PlantUML Diagrams. A lot of work was done here by Jacques Nomssi. See also the posts for a technique to extract Sequence diagrams from ABAP traces.

In October 2015 I heard the talk by Tudor Girba and learned about Moose analysis and the FAMIX meta-model. FAMIX is more granular than the UML class diagrams and contains invocations of methods and accesses to attributes. I wrote an extractor from SAP to Moose and was able to generate diagrams in Moose. See for instance this force attraction diagram:

Elements can be dragged an inspected. It is not only a picture. So it is possible to use such diagrams in projects. Links between loosely coupled applications are easy to see. As well as “islands”, classes that appear to have no connections to their surroundings.

But the main problems I had with other techniques that extract meta-models from the system stayed the same:

• Models can be very big
• Layout is not changeable
• Print needed for commenting

So I developed a second tool to address this problem. It is developed in Smalltalk and works on top of Roassal, the visualization framework that is used by Moose. It is hosted on Smalltalkhub. See Moose-Diagram for the github project page. The link to the smalltalkhub application is contained here.

Alexandre Bergel helped me to make Smalltalk code that made Roassal diagrams that looked a bit like UML class diagrams. But the red boxes are methods, the blue attributes, the gray classes and the rectangles packages.

I currently use the tool mostly for SAP applications. The extractor SAP2Moose interprets methods and attributes in a more general way

• Map logic to methods
• Map data to attributes

This interpretation has advantages in my opinion, but it is currently as far as I know only supported by the SAP2Moose extactor.

For a medium sized applications this made diagrams like this (here a logic to color connected elements was used to highlight some points):

The elements can be dragged and inspected, but in such a big model that is not easy. Here is a smaller application where the elements where ordered in a logical structure and some of the package boxes are suppressed:

This is easier to handle. Some lines are not nice and some boxes overlap. But this is not a big problem, because this is a diagram in Pharo. All elements can be dragged and inspected. So even if it looks not always nice, it appears not to be a problem. It is possible to display only subsets of the elements. For this certain elements are marked and the following statement is given: Suppress all other elements except me and elements that are either used by me to the n’th layer or that I am using to the m’th layer. By doing this for multiple elements a subset of an application is displayed in something I call currently layout. This appears to be very practical. It is possible to add comments. The positions and other settings are then stored to a file. This gives diagrams like this:

This resembles one of the mental models the developer had in the above mentioned comic Why you shouldn’t interrupt a programmer. And at least for me it works. This diagrams are comparable easy to make (Typically 2 minutes). Most elements are displayed in the diagram because they are connected to specified elements. If the coding is changed and the diagram is generated again, changes are automatically visible in the diagram. Deleted elements vanish, new elements appear if they are to be displayed by the above mentioned rule. And comments remain as long as no renaming was done. So when my real mental model collapsed, this diagrams remain and help me to reconstruct the real and often more complex mental mode.

This models are not perfect. Some elements are not extracted, sometimes there are bugs. It is just a model.

But it is for me so good, that I use it near to every day in my work.

• To remember where I am
• To plan what to do/li>
• To see dependencies
• I add a comment if something is missed in the model
• Please support. Experiment with it, feel free to open an issue in the Github repository even for problems that may appear small. Documentation is important, the first pull request by Lars Hvam the developer of abapGit was to correct spelling errors in the Readme. And abapGit has a much better documentation. To develop abapGit is required, to use it not. The extractor is only a simple ABAP report.

  If you work with SAP go to SAP2Moose

  If you work with other languages you can still use the enhancements to Moose, go to Moose Diagram enhancements for developers

  And a final thought.

  Do we need a standardization for an UML Dependency diagram ?