This article has the goal to show how to create a class diagram and how we can use it to understand code.
According to MSDN, a “Class diagrams help you understand the class structure of projects others have written (or that you wrote a long time ago). You can use them to customize, share and present project information with others.”
In this article we will use the sample Field Engineer from MSDN Samples which is an Azure Mobile Service sample, but where is not required to know about Azure Mobile Service and we will not talk about it. We only focus in the model classes as a sample.
After open the Field Engineer Sample in Visual Studio, we will find a folder with the name “Model”, here are an image with it
In this case we do not have so many classes, that can be great because can be easy to understand the model. Maybe a lot of developers will start open all files to see the code, but why not create a class diagram?
Let’s create first a class diagram for see an overview about the model.
Creating a class diagram
Selecting the Model folder and opening the context menu, click in “Add” and then “Class Diagram” as following
then define the name of the class diagram as following
clicking in “OK” the diagram file will be added to the project and will be opened, as following
now we can select all files in model folder and drag and drop it to the class designer area and the result will be
and now we should move each shape and should expand each one for see details.
For expand click in the arrow in top, as following
and the result will be
The class details
If we open the context menu under the shape we can select the “Class Details”
the result will be something like it
With this user interface is possible to see more details about the class and is possible to create/edit/delete/hide each property, method, event… without coding.
Understanding different icons
After expand all shapes we will find that some shapes show the Fields, Properties, and Methods (and can show events, nested classes…).
Let’s see the case of the MobileServiceContext
Looking to the image we can conclude
- The connectionStringName is private and is a const field;
- All properties are public;
- The method MobileServiceContext that is the constructor is public and the method OnModelCreating in private;
How is possible to conclude it?
Each icon means something, for example the symbol * in each item means it is private. The best way to understand the differences between each icon is to create a sample with each possible case.
Let’s see a fake class created for this purpose
When we select the shape and open the context menu we have options that allow to show/hide different details.
Let’s see the case for show the base class.
Show Base Class
After it and after expand the shape for MyBaseClass we will have something like it
In this moment, there are one point that can be important to defined, to show the diagram what is the most important information that should show in the diagram?
It depend what each developer likes or wants to see, but in general we can defined as a pattern, we should show only public properties, methods and events and hide all others (in some cases can be useful to show all defined as internal or protected).
Selecting the shape and the item we want to hide is possible using the context menu do this, as following
The option “Show all members” will revert it, but in some cases is better to use the Class Details for revert it, because we can have others items hidden that we want to keep hidden.
Each shape that hidden some item will show an icon that means it, here are an example
Returning to the Field Engineer Sample and choosing the class JobHistory, Job and Customer we will find that each one has a relationship with each others, let’s highlight it using a red and orange rectangle, as following
Let’s see how we can show the association for properties and for collection.
Show as Association
For properties which the data type is another class we can select the property in shape and in context menu should select the option “Show as Association” as following
Show as a Collection Association
and for properties that are collections/lists we can choose the option “Show as Collection Association” as following
and the result will be something like
The number of arrows will define it is a property or a collections, but using a good name can be enough to see the differences.
Show as property
By selecting in the arrow is possible to revert it, using the option “Show as property”.
The final class diagram
After define all arrows for all association and organizing the shapes we will have something as following
For this diagram, we can understand that the model has five classes and the MobileServiceContext is defined by these classes. Is clear the relationship between the classes which allow to conclude (for example)
- A job know its job histories and each job history refers to a job;
- A job knows which customer is associated and a customer can have more than one job;
A similar conclusion can be done for Equipment and Equipment Specifications.
Note: is possible to create arrows for the MobileServiceContext’s properties but it only will do some noise and is not important in this case to see these associations.
Each developer should customize the class diagram and there are no fixed rules for it. With this kind of diagram is very simple to understand the model and in some cases found mistakes like wrong names, wrong relationships or even missed features.
In conclusion, we can conclude that the class diagram is a very useful for understand the code made by us or by others, the relationship between the classes and an easy way to find mistakes. In some cases, with class diagram is possible to have a big picture about the application without see one line of code.