Exercise 2: Creating Diagrams

Effective diagramming is crucial for the communication of ideas in software engineering. This exercise explores some of the different ways in which you can draw diagrams for the work you do in COMP5911M.

Preparation

  1. You should already have a clone of your GitLab repository, created in the first exercise. Download exercise2.zip into the top-level directory of the repository and unzip the archive. This will give you a subdirectory named exercise2, containing three Java classes. Remove the Zip archive and then commit the newly added files:

    rm exercise2.zip
    git add exercise2
    git commit -m "Added code for diagrams exercise"
    
  2. The three classes come from an imaginary car rental application that generates a statement of the rental fees owed by a customer. Read exercise2/README.md for more details of this application. Then examine the three classes, to learn their structure and relationships.

Hand-Drawn Diagrams

Agile software development processes encourage the use of lightweight modelling techniques, in which diagrams are often sketched on paper or a whiteboard, or created using Post-it Notes. Important diagrams can be captured as digital photos which are then shared via a wiki.

  1. Sketch on paper a simple UML class diagram that represents the relationship between Customer, Rental and Car.

  2. Scan the diagram, or photograph it using your phone. Transfer the resulting image to your PC or a SoC Linux machine and use image editing software to adjust brightness, contrast, sharpness as necessary. Your goal should be to make the diagram as clear as possible. In addition, make sure you scale the image to a reasonable size: large enough that detail is legible, but not too large to display comfortably on a web page.

  3. Log in to gitlab.com and go to your project’s wiki. Create a new wiki page with the title ‘Exercise 2’. Add the heading ‘Hand-Drawn’ to the page, then click on the ‘Attach a file’ link to add your hand-drawn diagram.

GitLab Wiki Support for Diagrams

It is possible to generate diagrams directly inside GitLab wiki pages using Mermaid or PlantUML. These tools provide a text-based syntax for diagram specification. You will use PlantUML here.

Below is an example of how you specify a simple class diagram using PlantUML and the GitLab wiki’s Markdown syntax. The code is ‘fenced’ using triple backticks, rather than PlantUML’s @startuml and @enduml markers.

```plantuml
class BankAccount {
  - balance: int
}
class SavingsAccount {
  - interestRate: double
  + applyInterest()
}
BankAccount <|-- SavingsAccount
```

Here is the corresponding diagram:

Example of a PlantUML class diagram
  1. Consult the PlantUML docs for class diagrams or the PDF Guide to learn more about the syntax for class diagrams. Then edit the ‘Exercise 2’ wiki page created earlier and add the heading ‘PlantUML’, followed by a PlantUML class diagram for the car rental application. Use the Preview tab to see how the diagram will appear. When you are happy with the result, click the Save changes button.

  2. Consult the docs for sequence diagrams or the PDF Guide to learn about the syntax for sequence diagrams. Then edit the ‘Exercise 2’ page again and add a PlantUML sequence diagram showing the sequence of method calls that take place when an actor named RentalAgent invokes the statement() method on a Customer object and the fee for a single rental is calculated.

diagrams.net

diagrams.net is a free drawing tool than can produce many different types of diagram, including UML diagrams. It can be used online in a web browser but also provides a desktop app that can be used offline.

  1. Run the application. Use the Change storage link to choose ‘Device’ as the preferred storage medium for diagrams. (This means it will download diagram files to the machine you are using, rather than storing them in the cloud.) Then click the Create New Diagram button.

  2. The next dialog allows you to start from a blank diagram or from one of a number of different templates, of which several are for UML.

    Template selection dialog for diagrams.net

    diagrams.net templates

    In this case, just select ‘Blank Diagram’ and then click the Create button. When prompted for a save location, select the exercise2 directory in your repository, enter rental.drawio as the filename and click Save.

  3. Choose HelpQuick Start Video… from the menubar to watch a short (1m35s) video on how to draw diagrams. You can also use the Help menu to view keyboard shortcuts or search for help on a topic.

  4. Open the UML symbol library from the list of symbol libraries on the left of the screen:

    UML symbol library provided by diagrams.net

    UML symbol library

    Use these symbols to help you draw another version of the class diagram for the car rental application.

  5. Choose FileSave to save the diagram file. Make sure the saved file is in the exercise2 subdirectory of your repository. Use Git commands in the top-level directory of your repository to add, commit and push the changes:

    git add exercise2
    git commit -m "Added source file for class diagram"
    git push
    
  6. Back in diagrams.net, use FileExport asPNG… to create an image of your diagram1. Click Export and choose ‘Device’ as the destination for the image. Specify rental-classes.png as the filename, but do not put the image in your repository. (The image doesn’t need to be under version control, because the source file is already in the repository, and we can regenerate the image from that source file whenever we want.)

    Edit the ‘Exercise 2’ GitLab wiki page. Add a new heading, ‘diagrams.net’, then add rental-classes.png to the page under this heading.

  7. Optional: Click on the ‘+’ button at the bottom-left of the screen to add a new blank page to your diagram. Use this to experiment with drawing a sequence diagram equivalent to the one you created earlier using PlantUML. When you are happy with the result, save the document to the same file that you used before (rental.drawio, in the exercise2 directory of your repository). Use Git to add, commit and push the changes to this file.

    Export the diagram to a PNG image named rental-sequence.png, outside your repository. Then add this image to the ‘Exercise 2’ wiki page.

Other Tools

There are many other diagramming tools available. If you have the inclination, investigate one or more of the ones listed below.


  1. You may need to specify a larger Zoom factor (e.g., 200%) to ensure that the exported image has sufficient resolution to be fully legible. ↩︎