Class Diagram: An Easy Way to Understand Code

Scope

The purpose of this article is to show how to create a class diagram and how to use it to understand code.

Introduction

According to the MSDN, “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 that is an Azure Mobile Service sample, but it is not necessary to understand about the Azure Mobile Service and we will not talk about it. We only focus on the model classes as a sample.

Description

After opening the Field Engineer Sample in Visual Studio 2013, we will find a folder with the name “Model”, here is an image with it.



In this case we do not have so many classes. That can be great because it can be easy to understand the model. Maybe many developers will start opening all the files to see the code, but why not create a class diagram?

Let's first create a class diagram to see an overview of the model.

Creating a Class Diagram

Selecting the Model folder and opening the context menu, click in “Add” and then “Class Diagram” as in the following:



Then define the name of the class diagram as follows:



Clicking in “OK” the diagram file will be added to the project and will be opened, as in the following:



Now we can select all the files in the 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 to see the details.

Expanding classes

To expand, click in the arrow in the top, as in the 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 the following:



With this a user interface is possible. To see more details about the class and it is possible to create/edit/delete/hide each property, method, event and so on without coding.

Understanding various icons

After expanding all the shapes we will find that some shapes show the Fields, Properties and Methods (and can show events, nested classes and so on).

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 is 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.



Show Base Class

When we select the shape and open the context menu we have options that allow showing/hiding various details.

Let's see the case to show the base class.



Then after expanding the shape for MyBaseClass we will have something like:



At this moment, there is one point that is important to be defined. To show the diagram, what is the most important information that should be shown in the diagram?

It depends on what each developer likes or wants to see, but in general we can define it as a pattern. We should show only public properties, methods and events and hide all others (in some cases it can be useful to show everything defined as internal or protected).

Hide compartment

Selecting the shape and then the item we want to hide is possible and we can do that using the context menu, as in the following;



The option “Show all members” will revert it, but in some cases it is better to use the Class Details to revert it, because we can have other items hidden that we want to keep hidden.

Each shape hides some item that will show the icon that it means, here is an example.



Apply associations

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 in the following:



Let's see how to show the association for properties and for collections.

Show as Association

For properties that the data type is another class we can select the property in the shape and in the context menu we should select the option “Show as Association” as in the following:



Show as a Collection Association

For properties that are collections/lists we can choose the option “Show as Collection Association” as in the following:



And the result will be something like:



The number of arrows will define it as a property or a collection, but using a good name can be enough to see the differences.

Show as Property

By selecting in the arrow it is possible to revert it, using the option “Show as property”.



The final class diagram

After defining all the arrows for all the associations and organizing the shapes we will have something as in the following:



For this diagram, we can understand that the model has the five classes and the MobileServiceContext is defined by these classes. The relationship among the classes is clear (for example).

• A job knows 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 determination can be done for Equipment and Equipment Specifications.

Note: it is possible to create arrows for the MobileServiceContext's properties but that will only make some noise and it 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 it is very simple to understand the model and in some cases find mistakes like wrong names, wrong relationships or even missed features.

Conclusion

In conclusion, we can conclude that a class diagram is very useful for understanding the code made by us or by others, the relationship among the classes and an easy way to find mistakes. In some cases, with a class diagram it is possible to have a big picture about the application without see one line of code.