Class diagram: a easy way to understand code

Article
1/17/2024

Scope

This article shows how to create a class diagram and how we can use it to understand code.

Introduction

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.

Description

After open the Field Engineer Sample in Visual Studio, we will find a folder with the name "Model", here are an image with it

http://s29.postimg.org/uapyfnn3r/cd1.pngIn this case we do not have so many classes, that can be great because can be easy to understand the model. Many developers will start by opening files and read 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

http://s24.postimg.org/8ew8dg5ut/cd2.png

then define the name of the class diagram as following

http://s30.postimg.org/idjholpe9/cd3.png
clicking in "OK" the diagram file will be added to the project and will be opened, as following
http://s27.postimg.org/y067bw0kz/cd4.pngnow we can select all files in model folder and drag and drop it to the class designer area and the result will be

http://s23.postimg.org/nnkgjzaaj/cd5.png

and now we should move each shape and should expand each one for see details.

Expanding classes

For expand click in the arrow in top, as following
http://s30.postimg.org/olmwiladp/cd6.png

and the result will be
http://s3.postimg.org/x28b9pcir/cd7.png

The class details

If we open the context menu under the shape we can select the "Class Details"
http://s3.postimg.org/jmlak940z/cd8.png

the result will be something like it
http://s3.postimg.org/42dwtptwj/cd9.png

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

http://s27.postimg.org/dmytll2b7/cd10.png

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

http://s14.postimg.org/ofjl6o6cx/cd25.png
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

http://s30.postimg.org/en8dfcm35/cd12.png

After it and after expand the shape for MyBaseClass we will have something like it

http://s13.postimg.org/6y7ayco2v/cd23.png

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

Hide compartment

Selecting the shape and the item we want to hide is possible using the context menu do this, as following

http://s27.postimg.org/px66v2k8j/cd14.pngThe 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

http://s30.postimg.org/9jro4r4k1/cd15.png

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 following

http://s15.postimg.org/ipizzgowr/cd16.png

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

http://s29.postimg.org/s9pebo3av/cd18.pngShow as a Collection Association
and for properties that are collections/lists we can choose the option "Show as Collection Association" as following

http://s29.postimg.org/5jq9iok3b/cd17.png

and the result will be something like

http://s23.postimg.org/ukxxi7xzv/cd19.png

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

http://s15.postimg.org/b3tgqnrx7/cd20.png

The final class diagram

After define all arrows for all association and organizing the shapes we will have something as following

http://s14.postimg.org/mcdrcqvxt/cd24.png

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.

Conclusion

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.

Share via