This site is from a past semester! The current version will be here when the new semester starts.

Week 11 [Fri, Oct 23rd] - Topics

[W11.1] Writing Developer Documents

[W11.1a] Implementation → Documentation → Introduction → What

[W11.2] Design: Models

[W11.2a] Design → Introduction → What :
[W11.2b] Design → Modelling → Introduction → What :
[W11.2c] Design → Modelling → Introduction → How :

[W11.3] Class/Object Diagrams: Basics

[W11.3a] Design → Modelling → Modelling Structure → OO structures :
[W11.3b] Design → Modelling → Modelling Structure → Class diagrams - basic :
[W11.3c] Design → Modelling → Modelling Structure → Object diagrams :
[W11.3d] Tools → UML → Object versus class diagrams :
[W11.3e] Tools → UML → Class Diagrams → Associations as attributes :
[W11.3f] Tools → UML → Notes :

[W11.4] Class/Object Diagrams: Intermediate

[W11.4a] Design → Modelling → Modelling Structure → Class diagrams - intermediate :

Guidance for the item(s) below:

As you will be updating documentation of your project soon, here are some guidelines to help you with that.

[W11.1] Writing Developer Documents

Video

W11.1a

Implementation → Documentation → Introduction → What

Can explain the two types of developer docs

Developer-to-developer documentation can be in one of two forms:

Documentation for developer-as-user: Software components are written by developers and reused by other developers, which means there is a need to document how such components are to be used. Such documentation can take several forms:
- API documentation: APIs expose functionality in small-sized, independent and easy-to-use chunks, each of which can be documented systematically.
- Tutorial-style instructional documentation: In addition to explaining functions/methods independently, some higher-level explanations of how to use an API can be useful.

Example of API Documentation: String API.
Example of tutorial-style documentation: Java Internationalization Tutorial.

Example of API Documentation: string API.
Example of tutorial-style documentation: How to use Regular Expressions in Python

Documentation for developer-as-maintainer: There is a need to document how a system or a component is designed, implemented and tested so that other developers can maintain and evolve the code. Writing documentation of this type is harder because of the need to explain complex internal details. However, given that readers of this type of documentation usually have access to the source code itself, only some information needs to be included in the documentation, as code (and code comments) can also serve as a complementary source of information.

An example: se-edu/addressbook-level4 Developer Guide.

Another view proposed by Daniele Procida in this article is as follows:

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: tutorials, how-to guides, explanation and technical reference. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation - often immensely. ...

TUTORIALS

A tutorial:

is learning-oriented

allows the newcomer to get started

is a lesson

Analogy: teaching a small child how to cook

HOW-TO GUIDES

A how-to guide:

is goal-oriented

shows how to solve a specific problem

is a series of steps

Analogy: a recipe in a cookery book

EXPLANATION

An explanation:

is understanding-oriented

explains

provides background and context

Analogy: an article on culinary social history

REFERENCE

A reference guide:

is information-oriented

describes the machinery

is accurate and complete

Analogy: a reference encyclopedia article

Software documentation (applies to both user-facing and developer-facing) is best kept in a text format for ease of version tracking. A writer-friendly source format is also desirable as non-programmers (e.g., technical writers) may need to author/edit such documents. As a result, formats such as Markdown, AsciiDoc, and PlantUML are often used for software documentation.

Choose correct statements about API documentation.

a. They are useful for both developers who use the API and developers who maintain the API implementation.
b. There are tools that can generate API documents from code comments.
c. API documentation may contain code examples.

All

Guidance for the item(s) below:

One important objective of developer documentation is to explain the design and the implementation of the software, which usually uses diagrams as models of the design being described.

Let's learn what models are, and how they are useful even beyond mere documentation.

[W11.2] Design: Models

W11.2a :

Design → Introduction → What

Can explain what is software design

Design is the creative process of transforming the problem into a solution; the solution is also called design. _{-- 📖 Software Engineering Theory and Practice, Shari Lawrence; Atlee, Joanne M. Pfleeger}

Software design has two main aspects:

Product/external design: designing the external behavior of the product to meet the users' requirements. This is usually done by product designers with input from business analysts, user experience experts, user representatives, etc.
Implementation/internal design: designing how the product will be implemented to meet the required external behavior. This is usually done by software architects and software engineers.

W11.2b :

Design → Modelling → Introduction → What

Can explain models

A model is a representation of something else.

A class diagram is a model that represents a software design.

A model provides a simpler view of a complex entity because a model captures only a selected aspect. This omission of some aspects implies models are abstractions.

A class diagram captures the structure of the software design but not the behavior.

Multiple models of the same entity may be needed to capture it fully.

In addition to a class diagram (or even multiple class diagrams), a number of other diagrams may be needed to capture various interesting aspects of the software.

W11.2c :

Design → Modelling → Introduction → How

Can explain how models are used

In software development, models are useful in several ways:

a) To analyze a complex entity related to software development.

Some examples of using models for analysis:

Models of the i.e. the environment in which the software is expected to solve a problemproblem domain can be built to aid the understanding of the problem to be solved.
When planning a software solution, models can be created to figure out how the solution is to be built. An architecture diagram is such a model.

b) To communicate information among stakeholders. Models can be used as a visual aid in discussions and documentation.

Some examples of using models to communicate:

You can use an architecture diagram to explain the high-level design of the software to developers.
A business analyst can use a use case diagram to explain to the customer the functionality of the system.
A class diagram can be reverse-engineered from code so as to help explain the design of a component to a new developer.

c) As a blueprint for creating software. Models can be used as instructions for building software.

Some examples of using models as blueprints:

A senior developer draws a class diagram to propose a design for an OOP software and passes it to a junior programmer to implement.
A software tool allows users to draw UML models using its interface and the tool automatically generates the code based on the model.

Model Driven Development extra

Model-driven development (MDD), also called Model-driven engineering, is an approach to software development that strives to exploit models as blueprints. MDD uses models as primary engineering artifacts when developing software. That is, the system is first created in the form of models. After that, the models are converted to code using code-generation techniques (usually, automated or semi-automated, but can even involve manual translation from model to code). MDD requires the use of a very expressive modeling notation (graphical or otherwise), often specific to a given problem domain. It also requires sophisticated tools to generate code from models and maintain the link between models and the code. One advantage of MDD is that the same model can be used to create software for different platforms and different languages. MDD has a lot of promise, but it is still an emerging technology.

[W11.3] Class/Object Diagrams: Basics

Video

W11.3a :

Design → Modelling → Modelling Structure → OO structures

Can explain structure modeling of OO solutions

An OO solution is basically a network of objects interacting with each other. Therefore, it is useful to be able to model how the relevant objects are 'networked' together inside a software i.e. how the objects are connected together.

Given below is an illustration of some objects and how they are connected together. Note: the diagram uses an ad-hoc notation.

Note that these object structures within the same software can change over time.

Given below is how the object structure in the previous example could have looked like at a different time.

However, object structures do not change at random; they change based on a set of rules, as was decided by the designer of that software. Those rules that object structures need to follow can be illustrated as a class structure i.e. a structure that exists among the relevant classes.

Here is a class structure (drawn using an ad-hoc notation) that matches the object structures given in the previous two examples. For example, note how this class structure does not allow any connection between Genre objects and Author objects, a rule followed by the two object structures above.

UML Object Diagrams are used to model object structures and UML Class Diagrams are used to model class structures of an OO solution.

Here is an object diagram for the above example:

And here is the class diagram for it:

W11.3b :

Design → Modelling → Modelling Structure → Class diagrams - basic

Can use basic-level class diagrams

Contents of the panels given below belong to a different chapter; they have been embedded here for convenience and are collapsed by default to avoid content duplication in the printed version.

Classes form the basis of class diagrams.

Associations are the main connections among the classes in a class diagram.

The most basic class diagram is a bunch of classes with some solid lines among them to represent associations, such as this one.

An example class diagram showing associations between classes.

In addition, associations can show additional decorations such as association labels, association roles, multiplicity and navigability to add more information to a class diagram.

Here is the same class diagram shown earlier but with some additional information included:

Which association notations are shown in this diagram?

a. association labels
b. association roles
c. association multiplicity
d. class names

(a) (b) (c) (d)

Explanation: '1’ is a multiplicity, ‘mentored by’ is a label, and ‘mentor’ is a role.

Explain the associations, navigabilities, and multiplicities in the class diagram below:

Draw a class diagram for the code below. Show the attributes, methods, associations, navigabilities, and multiplicities.

class Box {
    private Item[] parts = new Item[10];
    private Item spareItem;
    private Lid lid; // lid of this box
    private Box outerBox;

    public void open() {
        // ...
    }
}

class Item {
    public static int totalItems;
}

class Lid {
    Box box; // the box for which this is the lid
}

W11.3c :

Design → Modelling → Modelling Structure → Object diagrams

Can use basic object diagrams

Object diagrams can be used to complement class diagrams. For example, you can use object diagrams to model different object structures that can result from a design represented by a given class diagram.

This question is based on the following question from another topic:

Draw a class diagram for the code below. Show the attributes, methods, associations, navigabilities, and multiplicities.

class Box {
    private Item[] parts = new Item[10];
    private Item spareItem;
    private Lid lid; // lid of this box
    private Box outerBox;

    public void open() {
        // ...
    }
}

class Item {
    public static int totalItems;
}

class Lid {
    Box box; // the box for which this is the lid
}

Draw an object diagram to match the code. Include objects of all three classes in your object diagram.

W11.3d :

Tools → UML → Object versus class diagrams

Can distinguish between class diagrams and object diagrams

Compared to the notation for class diagrams, object diagrams differ in the following ways:

Show objects instead of classes:
- Instance name may be shown
- There is a : before the class name
- Instance and class names are underlined
Methods are omitted
Multiplicities are omitted

Furthermore, multiple object diagrams can correspond to a single class diagram.

Both object diagrams are derived from the same class diagram shown earlier. In other words, each of these object diagrams shows ‘an instance of’ the same class diagram.

Which of these class diagrams match the given object diagram?

(1) (2)

Explanation: Both class diagrams allow one Unit object to be linked to one Item object.

W11.3e :

Tools → UML → Class Diagrams → Associations as attributes

Can show an association as an attribute

An association can be shown as an attribute instead of a line.

Association multiplicities and the default value can be shown as part of the attribute using the following notation. Both are optional.

name: type [multiplicity] = default value

The diagram below depicts a multi-player Square Game being played on a board comprising of 100 squares. Each of the squares may be occupied with any number of pieces, each belonging to a certain player.

A Piece may or may not be on a Square. Note how that association can be replaced by an isOn attribute of the Piece class. The isOn attribute can either be null or hold a reference to a Square object, matching the 0..1 multiplicity of the association it replaces. The default value is null.

The association that a Board has 100 Squares can be shown in either of these two ways:

Show each association as either an attribute or a line but not both. A line is preferred as it is easier to spot.

W11.3f :

Tools → UML → Notes

Can use UML notes

UML notes can augment UML diagrams with additional information. These notes can be shown connected to a particular element in the diagram or can be shown without a connection. The diagram below shows examples of both.

Example:

Follow up notes for the item(s) above:

Here is a worked examples covering the drawing of class/object diagrams using the basic notations:

Video [Example] Box, Item, Lid

Guidance for the item(s) below:

Having learned class/object diagrams basics, we can now move on to some intermediate CD/OD notations.

[W11.4] Class/Object Diagrams: Intermediate

Video

W11.4a :

Design → Modelling → Modelling Structure → Class diagrams - intermediate

Can use intermediate-level class diagrams

A class diagram can also show different types of relationships between classes: inheritance, compositions, aggregations, dependencies.

Modeling inheritance

Modeling composition

Modeling aggregation

Modeling dependencies

A class diagram can also show different types of class-like entities:

Modeling enumerations

Modeling abstract classes

Modeling interfaces

Which of these statements match the class diagram?

a. A Snake must belong to at least one Board.
b. A SnakeHeadSquare can contain only one Snake head.
c. A Square can contain a Snake head.
d. A Snake head can be in more than one SnakeHeadSquare.
e. The Board has exactly 5 Snakes.

~~(a)~~(b)(c)(d)(e)

Explanation:

(a) does not match because a Snake may or may not belong to a Board (multiplicity is 0..1)
(b) matches the diagram because the multiplicity given is 1
(c) matches the diagram because SnakeHeadSquare is a Square (due to inheritance)
(d) matches the diagram because the multiplicity given is *
(e) matches the diagram because the multiplicity given is 5

Explain the meaning of various class diagram notations in the following class diagram:

Consider the code below:

public interface Billable {
    void bill();
}

public abstract class Item
         implements Billable {
    public abstract void print();
}

public class StockItem extends Item {
    private Review review;
    private String name;

    public StockItem(
        String name, Rating rating) {

        this.name = name;
        this.review = new Review(rating);
    }

    @Override
    public void print() {
        //...
    }

    @Override
    public void bill() {
        //...
    }
}

public enum Rating {
    GOOD, OK, POOR
}

public class Review {
    private final Rating rating;

    public Review(Rating rating) {
        this.rating = rating;
    }
}

import java.util.List;

public class Inventory {
    private List<Item> items;

    public int getItemCount() {
        return items.size();
    }

    public void generateBill(Billable b) {
        // ...
    }

    public void add(Item s) {
        items.add(s);
    }
}

(a) Draw a class diagram to represent the code. Show all attributes, methods, associations, navigabilities, visibilities, known multiplicities, and association roles. Show associations as lines.
(b) Draw an object diagram to represent the situation where the inventory has one item named spanner and a review of POOR rating
i.e., new Inventory().add(new StockItem("spanner", new Review(Rating.POOR))).

Follow up notes for the item(s) above:

Now, you can try these worked examples:

Video Drawing class/object diagrams (intermediate) - Action, Task, History

Video Drawing class/object diagrams (intermediate) - Person, Inbox, Message

Video Drawing class/object diagrams (intermediate) - Person, Project, Task