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:
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:
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.
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.
One part in the software is almost isolated from the rest:
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.
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
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.
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.
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.
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.