Advantages of Graphical Notations #1: Understand existing Software

Reading Code vs. Reading Diagram

In software development one can highly profit from using graphical representations, instead of reading the code directly. This article uses a simple example, to demonstrate the advantages of diagrams over code. This first part, is about understanding the status quo of an existing software. 

Today at work, I had to redesign an existing XML Schema Definition (XSD) – no need for you to understand what it is. Just know, that it where 600 cryptic lines of code, split upon two files. Making designing bigger software on Code Level, is often the wrong decision, so I decided to work on a graphical representation of the files. I’ll explain how I started and why a graphical notation is superior to plain code on a few examples. Since the example is nonpublic work, I’ll turn down the resolution to hide some details.

I’ll turn down the resolution to hide some details

Understanding Status Quo

The first and most important part, when redesigning software is to understand the status quo. To acquire this understanding, you can read the code or read a diagram.

you can read the code or read a diagram

Reading the code

Reading the code, means reading all of this:

Complete Code: Status Quo (ca. 600 Lines of Code)

Now, can you tell me, where the circular dependency is, which needs to be removed? You can click the image to see a larger version. Still no success? Okay, let’s try something else.

Looking at a Diagram

Now take a look at this diagram:

Complete Diagram: Status Quo

It contains exactly the same information, as the Code above – no simplification. Can you see the circular dependency now? I admit, it’s hard at this resolution (you can click the Image, to show a larger version). If you can’t see it, write a comment, to get a hint.

Going deeper

Without raising the level of detail further, one can see some things in the diagram, which would take much longer to realize on code level.

Isolated Part

One part in the software is almost isolated from the rest:

This part of the Software only has one connection to the rest of the software.

The software units in the blue circle are only connected to the rest of the code through one connection. Why is that important? It means, you can ♫♪ break it, fix it, trash it, change it ♪♫♪ and only pay attention to a single point in your software, namely the connection.

Highest Parent

Most parts in the software contain other parts – the black diamond ♦ is a contains relation. But the part marked below is not contained by any other part, it has no parent.

the black diamond ♦ is a contains relation

Software Part without Parent.

Why is that important? It means, it is something like the main or core object of your software. It contains all other parts directly or indirectly. It’s probably the hub and pivot, when you integrate this software somewhere else. It keeps your software together in one piece.

Crossing Edges

I have a personal rule of a thumb for my diagrams: If the design can’t be arranged without crossing edges, it’s to complicated. So without knowledge of any further details, one can identify already six points in the diagram where my rule is broken. The components of the software are somehow wired to tightly around those red circles.

Crossing Edges are potential problems.

This is only my personal rule of a thumb. It’s not true in all cases. Critics could probably come up with a made up example, where these complicated structures are unavoidable. But those are very rare real world problems.

If the design can’t be arranged without crossing edges, it’s to complicated.

Conclusion

This was a quick trip to the lands of diagrams and so-called model driven design (MDD). On some examples I demonstrated how you can profit from diagrams, by having a better overview. This is one of my favorite topics in software engineering, so I guess more of those are up to come.

As always, I’d appreciate your feedback.

Cheers,

Waog