Advantages of Graphical Notations #1: Understand existing Software

Code vs. Diagram

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)

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

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

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

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.

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

Advertisements

11 thoughts on “Advantages of Graphical Notations #1: Understand existing Software

  1. Will you teach us how to turn code into diagrams next? 😀
    Unrelated: I’ve working with audio to waveform and spectrogram image rendering lately and code looks like a low bit depth, low sample rate sound wave 🙂
    Code or Wave

    Liked by 1 person

    • How code is turned into diagrams, depends on the kind of code/programming language you’re using. Maybe I’ll explain it on one or two examples. But it’s likely, that you need to put some research effort in, to find out how diagrams are generated and how to read them.

      In this blog-post I cheated a little bit. Because I didn’t want to try out different tools for XSDs, I “generated” the diagram by hand. Alternatively I could have chosen one of those examples: google, StackOverflow1 or Stackoverflow2.

      PS: had to take a really close look at your spectogram image, to realize if it’s my code or some different wave. Can you know listen to my code? 🙂

      Like

  2. Pingback: The Single Responsibility Principle | Waog

  3. Pingback: The Single Responsibility Principle | Waog

  4. Pingback: Code Smell: Feature Envy | Waog

  5. Pingback: Beyond coding – Levels of Errors in Software Development – Part 1 | Waog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s