As a solution architect I often get thrown into projects with a lot of legacy code and little or outdated documentation. My mandate is to suggest architectural changes that will reduce maintenance costs and ease further development. The first thing I focus on is to get an overview of the system and how it is structured with modules, components and classes. I have found that the best way to get this overview is to create a light weight UML class diagram. In this post I will show you how I prefer to create light weight UML class diagrams.
To start with I will explain what I mean by light weight UML class diagrams.
I want the diagrams to be easy to read and understand and I try to find the balance where the diagram is so light that non-technical persons (like product owner and project manager) understands it, but still it is technical enough so technical persons (like developers and architects) finds it useful.
I only use a few of the UML class diagram symbols:
In addition to these symbols I frame the packages that logically is related with different colours. I do this to make the diagrams more easy to read and it is also easier to understand the system when packages are framed like this. I use the same philosophy when creating diagrams as I use when writing clean code. I try to align boxes and symbol and make the diagram as easy to read as possible. I also only focus on the most important and essential packages and classes of the system. I do not add anything to the diagram that is not important, that will only be considered as noise.
You should also think twice before creating such diagrams. Ask yourself the question if it is really useful to create a diagram for that part of the system before you do so. Creating diagrams with the single purpose of creating a diagram is waste of your own time and also waste of time for the persons reading the diagram. Most people reads a diagram when they see one. I do so myself because I automatically thinks that since they bother creating a diagram it’s probably covering an important part of the system.
OK, enough talk, let’s look at how I create my light weight UML class diagrams. I use Microsoft Viso, any program can be used. I simply use Viso because I am very familiar with it and that’s the program where I quickest can draw these diagrams (since I have done this quite a few times I actually draw it faster in Visio then I would manage to do with pen and paper).
In Visio I select the UML Model Diagram found under Software and Database. I create a new page for each new module or large and complex components and packages. This way it is easier to focus on a different part of the system. Another thing I use to do it to add blank pages containing only some text explaining what I try to show with the diagrams on the following pages. When I am done with my diagrams and want to distribute them I have found that the best way to do so is to save the diagram as a pdf (you can do that directly from Visio). Then each page in Visio will be a page in the pdf file and separated with the blank pages (containing text explaining the system and diagrams or simply containing a header) this pdf file is all you need. No need to place your diagrams in documents with a lot of complimentary text. The keyword is as when developing software KISS (Keep It Simple, Stupid).
To give you some examples I took an old pet project of mine and created diagrams for the most important part of the solution. The project is a Windows Mobile 6.5 application using GPS to track, time and register your workout such as running, cycling etc.
First I will show the diagram for the main module called RunSmartWithMe. The RunSmartWithMe module is framed with a blue box showing packages and classes in this module. Packages framed with the red box is external modules/libraries that the RunSmartWithMe module depends on.
Next I create a diagram for the TechCon.Util module that the RunSmartWithMe module depends on.
And as the last diagram for this example I took the TechCon.UI module which RunSmartWithMe also depends on.
All these diagrams are in separate pages in Visio.
Some of you might think that these diagrams are not using UML correctly (and I guess that some of you might say that this is not a UML class diagram at all) and that might be true, but I don’t think that really matters. The most important is to be able to create compact and easy to read diagrams without spending too much time doing so.
I also saved the diagrams as a pdf file from Visio. You can have a look at the pdf file if you want to see the diagrams there.
By doing this exercise I have gained several benefits:
- Knowledge about the modules, components and structure of the system
- I have created good system documentation
- I have a good base to continue my work on suggesting architectural improvements
The next step now would be to create similar diagrams for the new system architecture.