Pros and Cons

The following description of the Joys of the Programming Craft was taken from Chapter 1 of the famous book The Mythical Man-Month, by Frederick P. Brooks.

Why is programming fun? What delights may its practitioner expect as his reward?

First is the sheer joy of making things. As the child delights in his mud pie, so the adult enjoys building things, especially things of his own design. I think this delight must be an image of God's delight in making things, a delight shown in the distinctness and newness of each leaf and each snowflake.

Second is the pleasure of making things that are useful to other people. Deep within, we want others to use our work and to find it helpful. In this respect the programming system is not essentially different from the child's first clay pencil holder "for Daddy's office."

Third is the fascination of fashioning complex puzzle-like objects of interlocking moving parts and watching them work in subtle cycles, playing out the consequences of principles built in from the beginning. The programmed computer has all the fascination of the pinball machine or the jukebox mechanism, carried to the ultimate.

Fourth is the joy of always learning, which springs from the nonrepeating nature of the task. In one way or another the problem is ever new, and its solver learns something: sometimes practical, sometimes theoretical, and sometimes both.

Finally, there is the delight of working in such a tractable medium. The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds his castles in the air, from air, creating by the exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures....

Yet the program construct, unlike the poet's words, is real in the sense that it moves and works, producing visible outputs separate from the construct itself. It prints results, draws pictures, produces sounds, moves arms. The magic of myth and legend has come true in our time. One types the correct incantation on a keyboard, and a display screen comes to life, showing things that never were nor could be.

Programming then is fun because it gratifies creative longings built deep within us and delights sensibilities we have in common with all men.

Not all is delight, however, and knowing the inherent woes makes it easier to bear them when they appear.

First, one must perform perfectly. The computer resembles the magic of legend in this respect, too. If one character, one pause, of the incantation is not strictly in proper form, the magic doesn't work. Human beings are not accustomed to being perfect, and few areas of human activity demand it. Adjusting to the requirement for perfection is, I think, the most difficult part of learning to program.

Next, other people set one's objectives, provide one's resources, and furnish one's information. One rarely controls the circumstances of his work, or even its goal. In management terms, one's authority is not sufficient for his responsibility. It seems that in all fields, however, the jobs where things get done never have formal authority commensurate with responsibility. In practice, actual (as opposed to formal) authority is acquired from the very momentum of accomplishment.

The dependence upon others has a particular case that is especially painful for the system programmer. He depends upon other people's programs. These are often maldesigned, poorly implemented, incompletely delivered (no source code or test cases), and poorly documented. So he must spend hours studying and fixing things that in an ideal world would be complete, available, and usable.

The next woe is that designing grand concepts is fun; finding nitty little bugs is just work. With any creative activity come dreary hours of tedious, painstaking labor, and programming is no exception.

Next, one finds that debugging has a linear convergence, or worse, where one somehow expects a quadratic sort of approach to the end. So testing drags on and on, the last difficult bugs taking more time to find than the first.

The last woe, and sometimes the last straw, is that the product over which one has labored so long appears to be obsolete upon (or before) completion. Already colleagues and competitors are in hot pursuit of new and better ideas. Already the displacement of one's thought-child is not only conceived, but scheduled.

This always seems worse than it really is. The new and better product is generally not available when one completes his own; it is only talked about. It, too, will require months of development. The real tiger is never a match for the paper one, unless actual use is wanted. Then the virtues of reality have a satisfaction all their own.

Of course the technological base on which one builds is always advancing. As soon as one freezes a design, it becomes obsolete in terms of its concepts. But implementation of real products demands phasing and quantizing. The obsolescence of an implementation must be measured against other existing implementations, not against unrealized concepts. The challenge and the mission are to find real solutions to real problems on actual schedules with available resources.

This then is programming, both a tar pit in which many efforts have floundered and a creative activity with joys and woes all its own. For many, the joys far outweigh the woes....

[Text and book cover source: Wikipedia]	[Fred Brooks photo source]

The Mythical Man-Month: Essays on Software Engineering is a book on software engineering and project management by Fred Brooks, whose central theme is that "adding manpower to a late software project makes it later". This idea is known as Brooks's law, and is presented along with the second-system effect and advocacy of prototyping.

Introduction

Object-Oriented Programming (OOP) is a programming paradigm. A programming paradigm guides programmers to analyze programming problems, and structure programming solutions, in a specific way.

Programming languages have traditionally divided the world into two parts—data and operations on data. Data is static and immutable, except as the operations may change it. The procedures and functions that operate on data have no lasting state of their own; they’re useful only in their ability to affect data.

This division is, of course, grounded in the way computers work, so it’s not one that you can easily ignore or push aside. Like the equally pervasive distinctions between matter and energy and between nouns and verbs, it forms the background against which we work. At some point, all programmers—even object-oriented programmers—must lay out the data structures that their programs will use and define the functions that will act on the data.

With a procedural programming language like C, that’s about all there is to it. The language may offer various kinds of support for organizing data and functions, but it won’t divide the world any differently. Functions and data structures are the basic elements of design.

Object-oriented programming doesn’t so much dispute this view of the world as restructure it at a higher level. It groups operations and data into modular units called objects and lets you combine objects into structured networks to form a complete program. In an object-oriented programming language, objects and object interactions are the basic elements of design.

_{-- Object-Oriented Programming with Objective-C, Apple}

Some other examples of programming paradigms are:

Some programming languages support multiple paradigms.

Basic

Every object has both state (data) and behavior (operations on data). In that, they’re not much different from ordinary physical objects. It’s easy to see how a mechanical device, such as a pocket watch or a piano, embodies both state and behavior. But almost anything that’s designed to do a job does, too. Even simple things with no moving parts such as an ordinary bottle combine state (how full the bottle is, whether or not it’s open, how warm its contents are) with behavior (the ability to dispense its contents at various flow rates, to be opened or closed, to withstand high or low temperatures).

It’s this resemblance to real things that gives objects much of their power and appeal. They can not only model components of real systems, but equally as well fulfill assigned roles as components in software systems.

_{-- Object-Oriented Programming with Objective-C, Apple}

Object Oriented Programming (OOP) views the world as a network of interacting objects.

OOP solutions try to create a similar object network inside the computer’s memory – a sort of a virtual simulation of the corresponding real world scenario – so that a similar result can be achieved programmatically.

OOP does not demand that the virtual world object network follow the real world exactly.

Every object has both state (data) and behavior (operations on data).

Every object has an interface and an implementation.

Every real world object has an interface that other objects can interact with and an implementation that supports the interface but may not be accessible to the other object.

Similarly, every object in the virtual world has an interface and an implementation.

Objects interact by sending messages.

Both real world and virtual world object interactions can be viewed as objects sending message to each other. The message can result in the sender object receiving a response and/or the receiving object’s state being changed. Furthermore, the result can vary based on which object received the message, even if the message is identical (see rows 1 and 2 in the example below).

Objects as Abstractions

The concept of Objects in OOP is an abstraction mechanism because it allows us to abstract away the lower level details and work with bigger granularity entities i.e. ignore details data formats and the method implementation details and work at the level of objects.

Encapsulation Of Objects

Encapsulation protects an implementation from unintended actions and from inadvertent access.
_{-- Object-Oriented Programming with Objective-C, Apple}

An object is an encapsulation of some data and related behavior in two aspects:

1. The packaging aspect: An object packages data and related behavior together into one self-contained unit.

2. The information hiding aspect: The data in an object is hidden from the outside world and are only accessible using the object's interface.

Basic

Writing an OOP program is essentially writing instructions that the computer uses to,

1. create the virtual world of object network, and
2. provide it the inputs to produce the outcome we want.

A class contains instructions for creating a specific kind of objects. It turns out sometimes multiple objects have the same behavior because they are of the same kind. Instructions for creating a one kind (or ‘class’) of objects can be done in one go and use that same instructions to instantiate (i.e. create) objects of that kind. We call such instructions a Class.

Let us use the UML notation to illustrate classes and objects under discussion.

Person class and some example instances of the Person class.

Class Level Members

While all objects of a class has the same attributes, each object has its own copy of the attribute value.

However, some attributes are not suitable to be maintained by individual objects. Instead, they should be maintained centrally, shared by all objects of the class. They are like ‘global variables’ but attached to a specific class. Such variables whose value is shared by all instances of a class are called class level attributes.

Similarly, when a normal method is being called, a message is being sent to the receiving object and the result may depend on the receiving object.

However, there can be methods related to a specific class but not suitable for sending message to a specific object of that class. Such methods that are called using the class instead of a specific instance are called class-level methods.

Class-level attributes and methods are collectively called class-level members (also called static members sometimes because some programming languages use the keyword static to identify class-level members). They are to be accessed using the class name rather than an instance of the class.

📦 A Student class with a class-level attribute and a method:

Enumerations

An Enumeration is a fixed set of values that can be considered as a data type.

An enumeration is often useful when using a regular data type such as int or String would allow invalid values to be assigned to a variable. e.g. if a variable can only take values 0 and 1, declaring it as an int would allow invalid values such as 2 to be assigned to it. But if you define an enumeration called Binary that has values 0 and 1 only, a variable of type Binary will never be assigned an invalid value such as 2 because the compiler is able to catch the error.

📦 Priority can be considered an enumeration because it has only three values.

Priority: HIGH, MEDIUM, LOW

Basic

Objects in an OO solution need to be connected to each other to form a network so that they can interact with each other. Such connections between objects are called associations.

📦 An object diagram example showing associations among objects. For example, there is an association between the AgeList object and the Main object.

Associations in an object structure can change over time.

Associations among objects are reflected correspondingly in the class diagram too, as it is the class diagram that dictates the nature of the associations allowed in the object structures.

📦 An example class diagram showing associations between classes.

Navigability

When two classes are linked by an association, it does not necessarily mean both classes know about each other. The concept of which class in the association knows about the other class is called navigability.

Multiplicity

Multiplicity is the aspect of an OOP solution that dictates how many objects take part in each association.

📦 This class diagram does not tell us multiplicities. For exaple, how many Calculator objects can be associated with one Main object? How many Main objects can be associated with one Calculator object? and so on.

Dependencies

Dependencies are objects that are not directly linked in the object network can still interact with each other. These are a weaker form of associations we call dependencies.

Composition

A composition is an association that represents a strong whole-part relationship. When the whole is destroyed, parts are destroyed too.

📦 A Board (used for playing board games) consists of Square objects.

Composition also implies that there cannot be cyclical links.

📦 In this ‘sub-folder’ association, a Folder cannot be a sub-folder of itself. If the diamond is removed, it is no longer a composition relationship and technically, allows a folder to be sub-folder of itself.

Aggregation

Aggregation represents a container-contained relationship. It is a weaker relationship than composition.

📦 Club acts as a container for Person objects. Person objects can survive without a Club object.

Association Classes

An association class represents additional information about an association. It is a normal class but plays a special role from a design point of view.

📦 A Man class and a Woman class is linked with a ‘married to’ association and there is a need to store the date of marriage. However, that data is related to the association rather than specifically owned by either the Man object or the Woman object. In such situations, an additional association class can be introduced, e.g. a Marriage class, to store such information.

What

The OOP concept Inheritance allows you to define a new class based on an existing class. For example, you can use inheritance to define an EvaluationReport class based on an existing Report class so that the EvaluationReport class does not have to duplicate code that is already implemented in the Report class.

📦 Example: The EvaluationReport inherits the wordCount attribute and the print() method from the base class Report.

• Other names for Base class: Parent class, Super class
• Other names for Derived class: Child class, Sub class, Extended class

A super class is said to be more general than the sub class. Conversely, a sub class is said to be more specialized than the super class.

Applying inheritance on a group of similar classes can result in the common parts among classes being extracted into more general classes.

📦 Man and Woman behaves the same way for the 'owes money' association. However, the two classes cannot be simply replaced with a more general class Person because of the need to distinguish between Man and Woman for the ‘marriage’ association. A solution is to add the Person class as a super class and let Man and Woman inherit from Person.

Inheritance implies the derived class can be considered as a sub-type of the base class (and the base class is a super-type of the derived class), resulting in an is a relationship.

📦 In this class diagrams of a Snakes and Ladders board game,

• SnakeHeadSquare is a Square  (a SnakeHeadSquare is a square in which the head of a snake appears)
• SnakeTailSquare is a Square

Inheritance relationships through a chain of classes can result in inheritance hierarchies (aka inheritance trees).

📦 Two inheritance hierarchies/trees are given below. Note that Parrot is a Bird as well as it is an Animal.

Multiple Inheritance is when a class inherits directly from multiple classes. Multiple inheritance is allowed among C++ classes but not among Java classes.

📦 The TA class inherits from the Staff class and the Student.

Overriding

Method overriding is when a sub-class changes the behavior inherited from the parent class by re-implementing the method. Overridden methods have the same name, same type signature, and same return type.

📦 In the diagram below,

• Report#print() method is overridden by EvaluationReport#print() method.
• Report#write(String) method is overridden by EvaluationReport#write(String) method.
• Report#read():String method is NOT overridden by EvaluationReport#read(int):String method.  Reason: the two methods have different signatures; EvaluationReport#read(int):String overloads (rather than overrides) the Report#read():String method.

Design → Object Oriented Programming →

Overloading

Method overloading is when there are multiple methods with the same name but different type signatures. Overloading is used to indicate that multiple operations do similar things but take different parameters.

Type Signature: The type signature of an operation is the type sequence of the parameters. The return type and parameter names are not part of the type signature. However, the parameter order is significant.

Method	Type Signature
int add(int X, int Y)	(int, int)
void add(int A, int B)	(int, int)
void m(int X, double Y)	(int, double)
void m(double X, int Y)	(double, int)

📦 In the class below, the calculate method is overloaded because the two methods have the same name but different type signatures (String) and (int[])

class RatingCalculator{
    void calculate(String matric) { ... }
    void calculate(int[] averages) { ... }
}

Overloading

Method overloading is when there are multiple methods with the same name but different type signatures. Overloading is used to indicate that multiple operations do similar things but take different parameters.

class RatingCalculator{
    void calculate(String matric) { ... }
    void calculate(int[] averages) { ... }
}

Interfaces

An interface is a behavior specification i.e. a collection of method specifications. If a class implements the interface, it means the class is able to support the behaviors specified by the said interface.

There are a number of situations in software engineering when it is important for disparate groups of programmers to agree to a "contract" that spells out how their software interacts. Each group should be able to write their code without any knowledge of how the other group's code is written. Generally speaking, interfaces are such contracts. _{--Oracle Docs on Java}

📦 SalariedStaff is an interface that contains two methods setSalary(int) and getSalary(). AcademicStaff implements the SalariedStaff interface.  That means an AcademicStaff object is able to support the behaviors setSalary(int) and getSalary(). That's why the same two methods also appear under the methods implemented by the AcademicStaff class (in blue)

A class implementing an interface results in an is-a relationship, just like in class inheritance.

Abstract Classes

An abstract method is simply the method interface without the implementation.

📦 The Account class has an abstract method (addInterest()).

Dynamic and Static Binding

Overridden methods are resolved using dynamic binding, and therefore resolves to the implementation in the actual type of the object.

Implementation → Object Oriented Programming →

Implementing Overriding

To override a method inherited from an ancestor class, simply re-implement the method in the target class.

📦 A simple example where the Report#print() method is overridden by EvaluationReport#print() method:

class Report{

    void print(){
        System.out.println("Printing report");
    }

}

class EvaluationReport extends Report{

    @Override  // this annotation is optional
    void print(){
        System.out.println("Printing evaluation report");
    }

}

class ReportMain{

    public static void main(String[] args){
        Report report = new Report();
        report.print(); // prints "Printing report"

        EvaluationReport evaluationReport = new EvaluationReport();
        evaluationReport.print(); // prints "Printing evaluation report"
    }
}

• Java - Overriding -- a tutorial by tutorialspoint.com

Which of these methods override another method?

• a
• b
• c
• d
• e

d

Explanation: Method overriding requires a method in a child class to use the same method name and same parameter sequence used by one of its ancestors

📦 Consider the code below. The declared type of s is Staff and it appears as if the adjustSalary(int) operation of the Staff class is invoked.

void adjustSalary(int byPercent) {
    for (Staff s: staff) {
        s.adjustSalary(byPercent);
    }
}

However, at runtime the adjustSalary(int) operation of the actual object will be called (i.e. adjustSalary(int) operation of Admin or Academic). If the actual object does not override that operation, the operation defined in the immediate superclass (in this case, Staff class) will be called.

In contrast, overloaded methods are resolved using static binding.

class Account {
    Account () {
        ...
    }
    
    Account (String name, String number, double balance) {
        ...
    }
    
    void save(int amount){
        ...
    }
}

class SavingAccount extends Account{
    
    void save(Double amount){
        ...
    }
}

class Account {
    Account () {
        // Signature: ()
        ...
    }
    Account (String name, String number, double balance) {
        // Signature: (String, String, double)
        ...
    }
}

void calculateGrade (int[] averages) { ... }
void calculateGrade (String matric) { ... }

Substitutability

Every instance of a subclass is an instance of the superclass, but not vice-versa. As a result, inheritance allows substitutability : the ability to substitute a child class object where a parent class object is expected.

📦 an Academic is an instance of a Staff, but a Staff is not necessarily an instance of an Academic. i.e. wherever an object of the superclass is expected, it can be substituted by an object of any of its subclasses.

The following code is valid because an AcademicStaff object is substitutable as a Staff object.

Staff staff = new AcademicStaff (); // OK

But the following code is not valid  because staff is declared as a Staff type and therefore its value may or may not be of type AcademicStaff, which is the type expected by variable academicStaff.

Staff staff;
...
AcademicStaff academicStaff = staff; // Not OK

Introduction

Take the example of writing a payroll application for a university to facilitate payroll processing of university staff. Suppose an adjustSalary(int) operation adjusts the salaries of all staff members. This operation will be executed whenever the university initiates a salary adjustment for its staff. However, the adjustment formula is different for different staff categories, say admin and academic. Here is one possible way of designing the classes in the Payroll system.

📦 Calling adjustSalary() method for each Staff type:

Here is the implementation of the adjustSalary(int) operation from the above design.

class Payroll1 {
    ArrayList< Admin > admins;
    ArrayList< Academic > academics;
    // ...

    void adjustSalary(int byPercent) {
        for (Admin ad: admins) {
            ad.adjustSalary(byPercent);
        }
        for (Academic ac: academics) {
            ac.adjustSalary(byPercent);
        }
    }
}

Note how processing is similar for the two staff types. It is as if the type of staff members is irrelevant to how they are processed inside this operation! If that is the case, can the staff type be "abstracted away" from this method? Here is such an implementation of adjustSalary(int):

class Payroll2 {
    ArrayList< Staff > staff;
    // ...

    void adjustSalary(int byPercent) {
        for (Staff s: staff) {
            s.adjustSalary(byPercent);
        }
    }
}

The above code is better in several ways:

• It is shorter.
• It is simpler.
• It is more flexible (this code will remain the same even if more staff types are added).

This does not mean we are getting rid of the Academic and Admin classes completely and replacing them with a more general class called Staff. Rather, this part of the code “treats” both Admin and Academic objects as one type called Staff.

For example, ArrayList staff contains both Admin and Academic objects although it treats all of them as Staff objects. However, when the adjustSalary(int) operation of these objects is called, the resulting salary adjustment will be different for Admin objects and Academic objects. Therefore, different types of objects are treated as a single general type, but yet each type of object exhibits a different kind of behavior. This is called polymorphism (literally, it means “ability to take many forms”). In this example, an object that is perceived as type Staff can be an Admin object or an Academic object.

Mechanism

Three concepts combine to achieve polymorphism: substitutability, operation overriding, and dynamic binding.

• Substitutability: Because of substitutability, you can write code that expects object of a parent class and yet use that code with objects of child classes. That is how polymorphism is able to treat objects of different types as one type.
• Overriding: To get polymorphic behavior from an operation, the operation in the superclass needs to be overridden in each of the subclasses. That is how overriding allows objects of different sub classes to display different behaviors in response to the same method call.
• Dynamic binding: Calls to overridden methods are bound to the implementation of the actual object's class dynamically during the runtime. That is how the polymorphic code can call the method of the parent class and yet execute the implementation of the child class.

Miscellaneous

What’s the difference between a Class, an Abstract Class, and an Interface?

• An interface is a behavior specification with no implementation.
• A class is a behavior specification + implementation.
• An abstract class is a behavior specification + a possibly incomplete implementation.

How does overriding differ from overloading?

Overloading is used to indicate that multiple operations do similar things but take different parameters. Overloaded methods have the same method name but different method signatures and possibly different return types.

Overriding is when a sub-class redefines an operation using the same method name and the same type signature. Overridden methods have the same name, same method signature, and same return type.

Implementing Classes

Given below is a tutorial you can refer to (from Oracle’s official Java tutorials) to learn how to implement java classes, in the unlikely case you don't know how to do that already.

• Classes, methods, variables – Start from the linked page and follow the next few steps in the tutorial

Implementing Class-Level Members

You can refer to Oracle’s official Java tutorial on class-level members to learn how to implement Java class-level members, in the unlikely case you don't know how to do that already.

Implementing Associations

We use instance level variables to implement associations.

A normal instance-level variable gives us a 0..1 multiplicity (also called optional associations) because a variable can hold a reference to a single object or null.

class Logic {
    Minefield minefield;
    ...
}

class Minefield {
    ...
}

A variable can be used to implement a 1 multiplicity too (also called compulsory associations).

class Logic {
    ConfigGenerator cg = new ConfigGenerator();
    ...
}

Bi-directional associations require matching variables in both classes.

class Foo {
    Bar bar;
    ...
}

class Bar {
    Foo foo;
    ...
}

To implement other multiplicities, choose a suitable data structure such as Arrays, ArrayLists, HashMaps, Sets, etc.

class Minefield {
    Cell[][] cell;
    ...
}

Implementing Dependencies

Dependencies result from interactions between objects that do not result in a long-term link between the said objects.

Example:

class TaxProcessor{
    double rate;

    void addTax(Taxable t){
        t.addTax(rate);
    }
}

The code above results in this dependency.

The code does not indicate an association between the two classes because the TaxProcessor object does not keep the Taxable object (i.e. it’s only a short-term interaction)

Implementing Composition

Composition too is implemented using a normal variable. If correctly implemented, the ‘part’ object will be deleted when the ‘whole’ object is deleted. Ideally, the ‘part’ object may not even be visible to clients of the ‘whole’ object.

Example:

class Car {
    private Engine engine;
  ...
}

Implementing Aggregation

Implementation is similar to that of composition except the containee object can exist even after the container object is deleted.

📦 Example:

class Car {
    Person driver;
    ...
    void drive(Person p) {
        driver = p;
    }
}

Implementing Association Classes

Note that while a special notation is used to indicate an association class, there is no special way to implement an association class.

Example:

At implementation level, an association class is most likely implemented as follows.

Implementing Inheritance

Implementing Overriding

To override a method inherited from an ancestor class, simply re-implement the method in the target class.

class Report{

    void print(){
        System.out.println("Printing report");
    }

}

class EvaluationReport extends Report{

    @Override  // this annotation is optional
    void print(){
        System.out.println("Printing evaluation report");
    }

}

class ReportMain{

    public static void main(String[] args){
        Report report = new Report();
        report.print(); // prints "Printing report"

        EvaluationReport evaluationReport = new EvaluationReport();
        evaluationReport.print(); // prints "Printing evaluation report"
    }
}

Implementing Overloading

An operation can be overloaded inside the same class or in sub/super classes.

class Account {
    Account () {
        ...
    }
    
    Account (String name, String number, double balance) {
        ...
    }
    
    void save(int amount){
        ...
    }
}

class SavingAccount extends Account{
    
    void save(Double amount){
        ...
    }
}

Implementing Interfaces

Java allows multiple inheritance among interfaces. A Java class can implement multiple interfaces (and inherit from one class).

📦 The design below is allowed by Java.

1. Staff interface inherits (note the solid lines) the interfaces TaxPayer and Citizen.
2. TA class implements both Student interface and the Staff interface.
3. Because of point 1 above, TA class has to implement all methods in the interfaces TaxPayer and Citizen.
4. Because of points 1,2,3, a TA is a Staff, is a TaxPayer and is a Citizen.

Java uses the interface keyword to declare interfaces and implements keyword to indicate that a class implements a given interface. Inheritance among interfaces uses the extends keyword, just like inheritance among classes.

interface TaxPayer {
    void payTax();
}

interface Citizen {
    void vote();
}

interface Staff extends Citizen, TaxPayer{
    void work();
}

interface Student {
    void learn();
}

class TA implements Student, Staff{

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

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

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

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

Implementing Abstract Classes

Use the abstract keyword to identify abstract classes/methods.

📦 Partial code below gives an example of how to declare abstract classes/methods.

abstract class Account {
    
    int number;
    
    abstract void addInterest();
    
    void close(){
        //...
    }
}

class CurrentAccount extends Account{

    @Override
    void addInterest() {
        //...
    }
}

In Java, if a class contains an abstract method, the class itself should be an abstract class  i.e. if any methods of the class is 'incomplete', the class itself is 'incomplete'.

Implementing Polymorphism

We can use inheritance to achieve polymorphism.

📦 Continuing with the example given in [ 🎓 OOP → Polymorphism → Introduction ], given below is the minimum code for Staff, Admin, and Academic classes that achieves the desired polymorphism.

Design → Object Oriented Programming → Polymorphism →

Introduction

Polymorphism:

The ability of different objects to respond, each in its own way, to identical messages is called polymorphism. _{-- Object-Oriented Programming with Objective-C, Apple}

Take the example of writing a payroll application for a university to facilitate payroll processing of university staff. Suppose an adjustSalary(int) operation adjusts the salaries of all staff members. This operation will be executed whenever the university initiates a salary adjustment for its staff. However, the adjustment formula is different for different staff categories, say admin and academic. Here is one possible way of designing the classes in the Payroll system.

📦 Calling adjustSalary() method for each Staff type:

Here is the implementation of the adjustSalary(int) operation from the above design.

class Payroll1 {
    ArrayList< Admin > admins;
    ArrayList< Academic > academics;
    // ...

    void adjustSalary(int byPercent) {
        for (Admin ad: admins) {
            ad.adjustSalary(byPercent);
        }
        for (Academic ac: academics) {
            ac.adjustSalary(byPercent);
        }
    }
}

Note how processing is similar for the two staff types. It is as if the type of staff members is irrelevant to how they are processed inside this operation! If that is the case, can the staff type be "abstracted away" from this method? Here is such an implementation of adjustSalary(int):

class Payroll2 {
    ArrayList< Staff > staff;
    // ...

    void adjustSalary(int byPercent) {
        for (Staff s: staff) {
            s.adjustSalary(byPercent);
        }
    }
}

Notice the following:

• Only one data structure ArrayList< Staff >. It contains both Admin and Academic objects but treats them as Staff objects
• Only one loop
• Outcome of the s.adjustSalary(byPercent) method call depends on whether s is an Academic or Admin object

The above code is better in several ways:

• It is shorter.
• It is simpler.
• It is more flexible (this code will remain the same even if more staff types are added).

This does not mean we are getting rid of the Academic and Admin classes completely and replacing them with a more general class called Staff. Rather, this part of the code “treats” both Admin and Academic objects as one type called Staff.

For example, ArrayList staff contains both Admin and Academic objects although it treats all of them as Staff objects. However, when the adjustSalary(int) operation of these objects is called, the resulting salary adjustment will be different for Admin objects and Academic objects. Therefore, different types of objects are treated as a single general type, but yet each type of object exhibits a different kind of behavior. This is called polymorphism (literally, it means “ability to take many forms”). In this example, an object that is perceived as type Staff can be an Admin object or an Academic object.

class Staff {
    String name;
    double salary;

    void adjustSalary(int percent) {
        // do nothing
    }
}

//------------------------------------------

class Admin extends Staff {

    @Override
    void adjustSalary(int percent) {
        salary = salary * percent;
    }
}

//------------------------------------------

class Academic extends Staff {

    @Override
    void adjustSalary(int percent) {
        salary = salary * percent * 2;
    }
}

//------------------------------------------

class Payroll {
    ArrayList< Staff > staff;
    // ...

    void adjustSalary(int byPercent) {
        for (Staff s: staff) {
            s.adjustSalary(byPercent);
        }
    }
}

Introduction

A software requirement specifies a need to be fulfilled by the software product.

A software project may be,

• a brown-field project i.e., develop a product to replace/update an existing software product
• a green-field project i.e., develop a totally new system with no precedent

In either case, requirements need to be gathered, analyzed, specified, and managed.

Requirements come from stakeholders.

Identifying requirements is often not easy. For example, stakeholders may not be aware of their precise needs, may not know how to communicate their requirements correctly, may not be willing to spend effort in identifying requirements, etc.

Non-Functional Requirements

There are two kinds of requirements:

1. Functional requirements specify what the system should do.
2. Non-functional requirements specify the constraints under which system is developed and operated.

We should spend extra effort in digging NFRs out as early as possible because NFRs are easier to miss  e.g., stakeholders tend to think of functional requirements first and sometimes they are critical to the success of the software.  E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Prioritizing Requirements

Requirements can be prioritized based the importance and urgency, while keeping in mind the constraints of schedule, budget, staff resources, quality goals, and other constraints.

A common approach is to group requirements into priority categories. Note that all such scales are subjective, and stakeholders define the meaning of each level in the scale for the project at hand.

Some requirements can be discarded if they are considered ‘out of scope’.

Quality of Requirements

Here are some characteristics of well-defined requirements ^{[📖 zielczynski]}:

• Unambiguous
• Testable (verifiable)
• Clear (concise, terse, simple, precise)
• Correct
• Understandable
• Feasible (realistic, possible)
• Independent
• Atomic
• Necessary
• Implementation-free (i.e. abstract)

Besides these criteria for individual requirements, the set of requirements as a whole should be

• Consistent
• Non-redundant
• Complete

Brainstorming

In a brainstorming session there are no "bad" ideas. The aim is to generate ideas; not to validate them. Brainstorming encourages you to "think outside the box" and put "crazy" ideas on the table without fear of rejection.

User Surveys

Surveys can be used to solicit responses and opinions from a large number of stakeholders regarding a current product or a new product.

Observation

Observing users in their natural work environment can uncover product requirements. Usage data of an existing system can also be used to gather information about how an existing system is being used, which can help in building a better replacement  e.g. to find the situations where the user makes mistakes when using the current system.

Interviews

Interviewing stakeholders and domain experts can give us useful information that project requirements.

Focus Groups

Focus groups are a kind of informal interview within an interactive group setting. A group of people (e.g. potential users, beta testers) are asked about their understanding of a specific issue, process, product, advertisement, etc.

Prototyping

Prototyping can uncover requirements, in particular, those related to how users interact with the system. UI prototypes are often used in brainstorming sessions, or in meetings with the users to get quick feedback from them.

^{[source: http://balsamiq.com/products/mockups]}

💡 Prototyping can be used for discovering as well as specifying requirements  e.g. a UI prototype can serve as a specification of what to build.

Product Surveys

Studying existing products can unearth shortcomings of existing solutions that can be addressed by a new product. Product manuals and other forms of technical documentation of an existing system can be a good way to learn about how the existing solutions work.

What

A normal textual description (i.e. prose) can be used to describe requirements. Prose is especially useful when describing abstract ideas such as the vision of a product.

❗️ Avoid using lengthy prose to describe requirements; they can be hard to follow.

What

Introduction

A common format for writing user stories is:

We can write user stories on index cards or sticky notes, and arrange on walls or tables, to facilitate planning and discussion. Alternatively, we can use a software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

Details

The {benefit} can be omitted if it is obvious.

❗️ It is recommended to confirm there is a concrete benefit even if you omit it from the user story. If not, we could end up adding features that have no real benefit.

We can add more characteristics to the {user role} to provide more context to the user story.

We can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. We can then break down these epics to multiple user stories of normal size.

We can add conditions of satisfaction to a user story to specify things that need to be true for the user story implementation to be accepted as ‘done’.

Other useful info that can be added to a user story includes (but not limited to)

• Priority: how important the user story is
• Size: the estimated effort to implement the user story
• Urgency: how soon the feature is needed

Usage

User stories capture user requirements in a way that is convenient for scoping, estimation and scheduling.

[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. _{[Mike Cohn, MountainGoat Software 🔗]}

User stories differ from traditional requirements specifications mainly in the level of detail. User stories should only provide enough details to make a reasonably low risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the requirements. [more...]

User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.

While use cases can be recorded on physical paper in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not co-located.

Introduction

A use case describes an interaction between the user and the system for a specific functionality of the system.

UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually, providing a visual ‘table of contents’ of the use cases of a system. In the example below, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.

Use cases capture the functional requirements of a system.

Identifying

A use case is an interaction between a system and its actors.

Actors in Use Cases

A use case can involve multiple actors.

An actor can be involved in many use cases.

A single person/system can play many roles.

Many persons/systems can play a single role.

Use cases can be specified at various levels of detail.

Details

Writing use case steps

Extensions are "add-on"s to the MSS that describe exceptional/alternative flow of events. They describe variations of the scenario that can happen if certain things are not as expected by the MSS. Extensions appear below the MSS.

📦 This example adds some extensions to the use case in the previous example.

• System: Online Banking System (OBS)
• Use case: UC23 - Transfer Money
• Actor: User
• MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. OBS transfers the money and displays the new account balance.
  6. Use case ends.
• Extensions:
  1. 3a. OBS detects an error in the entered data.
     1. 3a1. OBS requests for the correct data.
     2. 3a2. User enters new data.
     3. Steps 3a1-3a2 are repeated until the data entered are correct.
     4. Use case resumes from step 4.
  2. 3b. User requests to effect the transfer in a future date.
     1. 3b1. OBS requests for confirmation.
     2. 3b2. User confirms future transfer.
     3. Use case ends.
  3. *a. At any time, User chooses to cancel the transfer.
     1. *a1. OBS requests to confirm the cancellation.
     2. *a2. User confirms the cancellation.
     3. Use case ends.
  4. *b. At any time, 120 seconds lapse without any input from the User.
     1. *b1. OBS cancels the transfer.
     2. *b2. OBS informs the User of the cancellation.
     3. Use case ends.

Note that the numbering style is not a universal rule but a widely used convention. Based on that convention,

• either of the extensions marked 3a. and 3b. can happen just after step 3 of the MSS.
• the extension marked as *a. can happen at any step (hence, the *).

When separating extensions from the MSS, keep in mind that the MSS should be self-contained. That is, the MSS should give us a complete usage scenario.

Also note that it is not useful to mention events such as power failures or system crashes as extensions because the system cannot function beyond such catastrophic failures.

In use case diagrams you can use the << extend >> arrows to show extensions. Note the direction of the arrow is from the extension to the use case it extends and the arrow uses a dashed line.

A use case can include another use case. Underlined text is commonly used to show an inclusion of a use case.

📦 This use case includes two other use cases, one in step 1 and one in step 2.

• Software System: LearnSys
• Use case: UC01 - Conduct Survey
• Actors: Staff, Student
• MSS:
  1. Staff creates the survey (UC44).
  2. Student completes the survey (UC50).
  3. Staff views the survey results.
  4. Use case ends.

Inclusions are useful,

• when you don't want to clutter a use case with too many low-level steps.
• when a set of steps is repeated in multiple use cases.

We use a dotted arrow and a << include >> annotation to show use case inclusions in a use case diagram. Note how the arrow direction is different from the << extend >> arrows.

Usage

You can use actor generalization in use case diagrams using a symbol similar to that of UML notation for inheritance.

📦 In this example, actor Blogger can do all the use cases the actor Guest can do, as a result of the actor generalization relationship given in the diagram.

💡 Do not over-complicate use case diagrams by trying to include everything possible. A use case diagram is a brief summary of the use cases that is used as a starting point. Details of the use cases can be given in the use case descriptions.

Some include ‘System’ as an actor to indicate that something is done by the system itself without being initiated by a user or an external system.

📦 The diagram below can be used to indicate that the system generates daily reports at midnight.

However, others argue that only use cases providing value to an external user/system should be shown in the use case diagram. For example, they argue that ‘view daily report’ should be the use case and generate daily report is not to be shown in the use case diagram because it is simply something the system has to do to support the view daily report use case.

We recommend that you follow the latter view (i.e. not to use System as a user). Limit use cases for modeling behaviors that involve an external actor.

UML is not very specific about the text contents of a use case. Hence, there are many styles for writing use cases. For example, the steps can be written as a continuous paragraph. Use cases should be easy to read. Note that there is no strict rule about writing all details of all steps or a need to use all the elements of a use case.

There are some advantages of documenting system requirements as use cases:

• Because they use a simple notation and plain English descriptions, they are easy for users to understand and give feedback.
• They decouple user intention from mechanism (note that use cases should not include UI-specific details), allowing the system designers more freedom to optimize how a functionality is provided to a user.
• Identifying all possible extensions encourages us to consider all situations that a software product might face during its operation.
• Separating typical scenarios from special cases encourages us to optimize the typical scenarios.

One of the main disadvantages of use cases is that they are not good for capturing requirements that does not involve a user interacting with the system. Hence, they should not be used as the sole means to specify requirements.

What

What

A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most Non Functional Requirements will be listed.

What

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

What

Most programs are written to solve complex problems involving large amounts of intricate details. It is impossible to deal with all these details at the same time. The guiding principle of abstraction stipulates that we capture only details that are relevant to the current perspective or the task at hand.

Ignoring lower level data items and thinking in terms of bigger entities is called data abstraction.

Control abstraction abstracts away details of the actual control flow to focus on tasks at a simplified level.

Abstraction can be applied repeatedly to obtain progressively higher levels of abstractions.

What

Coupling is a measure of the degree of dependence between components, classes, methods, etc. Low coupling indicates that a component is less dependent on other components. High coupling (aka tight coupling or strong coupling) is discouraged due to the following disadvantages:

• Maintenance is harder because a change in one module could cause changes in other modules coupled to it (i.e. a ripple effect).
• Integration is harder because multiple components coupled with each other have to be integrated at the same time.
• Testing and reuse of the module is harder due to its dependence on other modules.

📦 In the example below, design A appears to have a more coupling between the components than design B.

How

X is coupled to Y if a change to Y can potentially require a change in X.

class Foo{
    ...
    new Bar().read();
    ...
}

class Bar{
    void read(){
        ...
    }
    
    void write(){
        ...
    }
}

Types of Coupling

Some examples of different coupling types:

• Content coupling: one module modifies or relies on the internal workings of another module  e.g., accessing local data of another module
• Common/Global coupling: two modules share the same global data
• Control coupling: one module controlling the flow of another, by passing it information on what to do  e.g., passing a flag
• Data coupling: one module sharing data with another module  e.g. via passing parameters
• External coupling: two modules share an externally imposed convention  e.g., data formats, communication protocols, device interfaces.
• Subclass coupling: a class inherits from another class. Note that a child class is coupled to the parent class but not the other way around.
• Temporal coupling: two actions are bundled together just because they happen to occur at the same time  e.g. extracting a contiguous block of code as a method although the code block contains statements unrelated to each other

What

Cohesion is a measure of how strongly-related and focused the various responsibilities of a component are. A highly-cohesive component keeps related functionalities together while keeping out all other unrelated things.

Higher cohesion is better. Disadvantages of low cohesion (aka weak cohesion):

• Impedes the understandability of modules as it is difficult to express module functionalities at a higher level.
• Lowers maintainability because a module can be modified due to unrelated causes  (reason: the module contains code unrelated to each other) or many many modules may need to be modified to achieve a small change in behavior  (reason: because the code realated to that change is not localized to a single module).
• Lowers reusability of modules because they do not represent logical units of functionality.

How

Cohesion can be present in many forms. Some examples:

• Code related to a single concept is kept together, e.g. the Student component handles everything related to students.
• Code that is invoked close together in time is kept together, e.g. all code related to initializing the system is kept together.
• Code that manipulates the same data structure is kept together, e.g. the GameArchive component handles everything related to the storage and retrieval of game sessions.

What

A model is a representation of something else.

A class diagram is a diagram drawn using the UML modelling notation.
📦 An example class diagram:

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.

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

How

In software development, models are useful in several ways:

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

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

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

UML Models

The following diagram uses the class diagram notation to show the different types of UML diagrams.

Class Diagrams (Basics)

Associations among objects/classes play an important role in an OO solution.

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:

Object Diagrams

Object Oriented Domain Models

The analysis process for identifying objects and object classes is recognized as one of the most difficult areas of object-oriented development. _{--Ian Sommerville, in the book Software Engineering}

Class diagrams can also be used to model objects in the problem domain (i.e. to model how objects actually interact in the real world, before emulating them in the solution). Class diagrams are used to model the problem domain are called conceptual class diagrams or OO domain models (OODMs).

📦 OO domain model of a snakes and ladders game is given below.

Description: Snakes and ladders game is played by two or more players using a board and a die. The board has 100 squares marked 1 to 100. Each player owns one piece. Players take turns to throw the die and advance their piece by the number of squares they earned from the die throw. The board has a number of snakes. If a player’s piece lands on a square with a snake head, the piece is automatically moved to the square containing the snake’s tail. Similarly, a piece can automatically move from a ladder foot to the ladder top. The player whose piece is the first to reach the 100th square wins.

The above OO domain model omits the ladder class for simplicity. It can be included in a similar fashion to the Snake class.

OODMs do not contain solution-specific classes (i.e. classes that are used in the solution domain but do not exist in the problem domain). For example, a class called DatabaseConnection could appear in a class diagram but not usually in an OO domain model because DatabaseConnection is something related to a software solution but not an entity in the problem domain.

OODMs represents the class structure of the problem domain and not their behavior, just like class diagrams. To show behavior, use other diagrams such as sequence diagrams.

OODM notation is similar to class diagram notation but typically omit methods and navigability.

Deployment Diagrams

A deployment diagram shows a system's physical layout, revealing which pieces of software run on which pieces of hardware.

📦 An example deployment diagram:

_{source:https://commons.wikimedia.org}

Component Diagrams

A component diagram is used to show how a system is divided into components and how they are connected to each other through interfaces.

Package Diagrams

A package diagram shows packages and their dependencies. A package is a grouping construct for grouping UML elements (classes, use cases, etc.).

Composite Structure Diagrams

A composite structure diagram hierarchically decomposes a class into its internal structure.

📦 Here is an example composite structure diagram:

_{source:https://commons.wikimedia.org}

Activity Diagrams

Software projects often involve workflows. Workflows define the flow in which a process or a set of tasks is executed.

Understanding such workflows is important for the success of the software project. UML  activity diagrams (AD) can model workflows.  Flow charts is another type of diagrams that can model workflows. Activity diagrams are the UML equivalent of flow charts.

📦 An example activity diagram _{[source:wikipeida]}:

The most basic activity diagram is simply a linear sequence of actions.

Some workflows have alternate paths where only one of the alternate paths is taken based on some condition.

In some workflows, multiple paths happen in parallel.

Sequence Diagrams - Basic

Sequence diagrams model interactions between entities for a given scenario.

📦 Consider the code below.

class Machine {

    Unit producePrototype() {
        Unit prototype = new Unit();
        for (int i = 0; i < 5; i++) {
            prototype.stressTest();
        }
        return prototype;
    }
}

class Unit {

    public void stressTest() {

    }
}

Here is the sequence diagram to model the interactions for the method call prouducePrototype() on a Machine object.

Use Case Diagrams

Use case diagrams model the mapping between features of a system and its user roles.

📦 A simple use case diagram:

Timing Diagrams

A timing diagram focus on timing constraints.

📦 Here is an example timing diagram:

_{Adapted from: UML Distilled by Martin Fowler}

Interaction Overview Diagrams

An Interaction overview diagrams is a combination of activity diagrams and sequence diagrams.

📦 An example:

_{source:https://commons.wikimedia.org}

Communication Diagrams

A Communication diagrams are like sequence diagrams but emphasize the data links between the various participants in the interaction rather than the sequence of interactions.

📦 An example:

_{Adapted from: UML Distilled by Martin Fowler}

State Machine Diagrams

A State Machine Diagram models state-dependent behavior.

Often, state-dependent behavior displayed by an object in a system is simple enough that it needs no extra attention; such a behavior can be as simple as a conditional behavior like if x>y, then x=x-y. Occasionally, objects may exhibit state-dependent behavior that is complex enough such that it needs to be captured into a separate model. Such state-dependent behavior can be modelled using UML state machine diagrams (SMD for short, sometimes also called ‘state charts’, ‘state diagrams’ or ‘state machines’).

An SMD views the life-cycle of an object as consisting of a finite number of states where each state displays a unique behavior pattern. An SMD captures information such as the states an object can be in, during its lifetime, and how the object responds to various events while in each state and how the object transits from one state to another. In contrast to sequence diagrams that capture object behavior one scenario at a time, SMDs capture the object’s behavior over its full life cycle.

📦 An SMD for the Minesweeper game.

Introduction

You can use models to analyze and design a software before you start coding.

Suppose You are planning to implement a simple minesweeper game that has a text based UI and a GUI. Given below is a possible OOP design for the game.

Before jumping into coding, you may want to find out things such as,

• Is this class structure is able to produce the behavior we want?
• What API should each class have?
• Do we need more classes?

To answer those questions, you can analyze the how the objects of these classes will interact with each other to produce the behavior you want.

Basic

As mentioned in [ Design → Modeling → Modeling a Solutions → Introduction], this is the Minesweeper design you have come up with so far. Our objective is to analyze, evaluate, and refine that design.

Design → Modeling → Modeling a Solution →

Introduction

You can use models to analyze and design a software before you start coding.

Suppose You are planning to implement a simple minesweeper game that has a text based UI and a GUI. Given below is a possible OOP design for the game.

Before jumping into coding, you may want to find out things such as,

• Is this class structure is able to produce the behavior we want?
• What API should each class have?
• Do we need more classes?

To answer those questions, you can analyze the how the objects of these classes will interact with each other to produce the behavior you want.

Let us start by modelling a sample interaction between the person playing the game and the TextUi object.

newgame and clear x y represent commands typed by the Player on the TextUi.

How does the TextUi object carry out the requests it has received from player? It would need to interact with other objects of the system. Because the Logic class is the one that controls the game logic, the TextUi needs to collaborate with Logic to fulfill the newgame request. Let us extend the model to capture that interaction.

W = Width of the minefield; H = Height of the minefield

The above diagram assumes that W and H are the only information TextUi requires to display the minefield to the Player. Note that there could be other ways of doing this.
The Logic methods we conceptualized in our modelling so far are:

Now, let us look at what other objects and interactions are needed to support the newGame() operation. It is likely that a new Minefield object is created when the newGame() method is called.

Note that the behavior of the Minefield constructor has been abstracted away. It can be designed at a later stage.

Given below are the interactions between the player and the Text UI for the whole game.

Intermediate

Continuing with the example in [ Design → Modeling → Modeling a Solution → Basic], next let us model how the TextUi interacts with the Logic to support the mark or clear operations until the game is won or lost.

Design → Modeling → Modeling a Solution →

Basic

As mentioned in [ Design → Modeling → Modeling a Solutions → Introduction], this is the Minesweeper design you have come up with so far. Our objective is to analyze, evaluate, and refine that design.

Design → Modeling → Modeling a Solution →

Introduction

You can use models to analyze and design a software before you start coding.

Suppose You are planning to implement a simple minesweeper game that has a text based UI and a GUI. Given below is a possible OOP design for the game.

Before jumping into coding, you may want to find out things such as,

• Is this class structure is able to produce the behavior we want?
• What API should each class have?
• Do we need more classes?

To answer those questions, you can analyze the how the objects of these classes will interact with each other to produce the behavior you want.

Let us start by modelling a sample interaction between the person playing the game and the TextUi object.

newgame and clear x y represent commands typed by the Player on the TextUi.

How does the TextUi object carry out the requests it has received from player? It would need to interact with other objects of the system. Because the Logic class is the one that controls the game logic, the TextUi needs to collaborate with Logic to fulfill the newgame request. Let us extend the model to capture that interaction.

W = Width of the minefield; H = Height of the minefield

The above diagram assumes that W and H are the only information TextUi requires to display the minefield to the Player. Note that there could be other ways of doing this.
The Logic methods we conceptualized in our modelling so far are:

Now, let us look at what other objects and interactions are needed to support the newGame() operation. It is likely that a new Minefield object is created when the newGame() method is called.

Note that the behavior of the Minefield constructor has been abstracted away. It can be designed at a later stage.

Given below are the interactions between the player and the Text UI for the whole game.

💡 Note that a similar technique can be used when discovering/defining the architecture-level APIs.

📺 Defining the architecture-level APIs for a small Tic-Tac-Toe game:

This interaction adds the following methods to the Logic class

• clearCellAt(int x, int y)
• markCellAt(int x, int y)
• getGameState() :GAME_STATE (GAME_STATE: READY, IN_PLAY, WON, LOST, …)

And it adds the following operation to Logic API:

• getAppearanceOfCellAt(int,int):CELL_APPEARANCE (CELL_APPEARANCE: HIDDEN, ZERO, ONE, TWO, THREE, …, MARKED, INCORRECTLY_MARKED, INCORRECTLY_CLEARED)

In the above design, TextUi does not access Cell objects directly. Instead, it gets values of type CELL_APPEARANCE from Logic to be displayed as a minefield to the player. Alternatively, each cell or the entire Minefield can be passed directly to TextUi.

Here is the updated class diagram:

The above is for the case when Actor Player interacts with the system using a text UI. Additional operations (if any) required for the GUI can be discovered similarly. Suppose Logic supports a reset() operation. We can model it like this:

Our current model assumes that the Minefield object has enough information (i.e. H, W, and mine locations) to create itself.

An alternative is to have a ConfigGenerator object that generates a string containing the minefield information as shown below.

In addition, getWidth(), getHeight(), markCellAt(x,y) and clearCellAt(x,y) can be handled like this.

The updated class diagram:

How is getGameState() operation supported? Given below are two ways (there could be other ways):

1. Minefield class knows the state of the game at any time. Logic class retrieves it from the Minefield class as and when required.
2. Logic class maintains the state of the game at all times.

Here’s the SD for option 1.

Here’s the SD for option 2. Here, assume that the game state is updated after every mark/clear action.

It is now time to explore what happens inside the Minefield constructor? One way is to design it as follows.

Now let us assume that Minesweeper supports a ‘timing’ feature.

Updated class diagram:

What

The software architecture of a program or computing system is the structure or structures of the system, which comprise software elements, the externally visible properties of those elements, and the relationships among them. Architecture is concerned with the public side of interfaces; private details of elements—details having to do solely with internal implementation—are not architectural. _{-- Software Architecture in Practice (2nd edition), Bass, Clements, and Kazman}

The software architecture shows the overall organization of the system and can be viewed as a very high-level design. It usually consists of a set of interacting components that fit together to achieve the required functionality. It should be a simple and technically viable structure that is well-understood and agreed-upon by everyone in the development team, and it forms the basis for the implementation.

📦 A possible architecture for a Minesweeper game

Main components:

• GUI: Graphical user interface
• TextUi: Textual user interface
• ATD: An automated test driver used for testing the game logic
• Logic: computation and logic of the game
• Store: storage and retrieval of game data (high scores etc.)

The architecture is typically designed by the software architect, who provides the technical vision of the system and makes high-level (i.e. architecture-level) technical decisions about the project.

Reading

Architecture diagrams are free-form diagrams. There is no universally adopted standard notation for architecture diagrams. Any symbol that reasonably describes the architecture may be used.

Drawing

While architecture diagrams have no standard notation, try to follow these basic guidelines when drawing them.

• Minimize the variety of symbols. If the symbols you choose do not have widely-understood meanings  e.g. A drum symbol is widely-understood as representing a database, explain their meaning.

• Avoid the indiscriminate use of double-headed arrows to show interactions between components.

📦Consider the two architecture diagrams of the same software given below. Because Diagram 2 uses double headed arrows, the important fact that GUI has a bi-directional dependency with the Logic component is no longer captured.

What

Software architectures follow various high-level styles (aka architectural patterns), just like building architectures follow various architecture styles.

What

In the n-tier style, higher layers make use of services provided by lower layers. Lower layers are independent of higher layers. Other names: multi-layered, layered.

What

The client-server style has at least one component playing the role of a server and at least one client component accessing the services of the server. This is an architectural style used often in distributed applications.

📦 The online game and teh Web application below uses the client-server style.

What

The transaction processing style divides the workload of the system down to a number of transactions which are then given to a dispatcher that controls the execution of each transaction. Task queuing, ordering, undo etc. are handled by the dispatcher.

📦 In this example from a Banking system, transactions are generated by the terminals used by tellers which are then sent to a central dispatching unit which in turn dispatches the transactions to various other units to execute.

What

The service-oriented architecture (SOA) style builds applications by combining functionalities packaged as programmatically accessible services. SOA aims to achieve interoperability between distributed services, which may not even be implemented using the same programming language. A common way to implement SOA is through the use of XML web services where the web is used as the medium for the services to interact, and XML is used as the language of communication between service providers and service users.

📦 Suppose that Amazon.com provides a web service for customers to browse and buy merchandise, while HSBC provides a web service for merchants to charge HSBC credit cards. Using these web services, an ‘eBookShop’ web application can be developed that allows HSBC customers to buy merchandise from Amazon and pay for them using HSBC credit cards. Because both Amazon and HSBC services follow the SOA architecture, their web services can be reused by the web application, even if all three systems use different programming platforms.

What

Event-driven style controls the flow of the application by detecting events from event emitters and communicating those events to interested event consumers . This architectural style is often used in GUIs.

📦 When the ‘button clicked’ event occurs in a GUI, that event can be transmitted to components that are interested in reacting to that event. Similarly, events detected at a Printer port can be transmitted to components related to operating the Printer. The same event can be sent to multiple consumers too.

More Styles

Other well-known architectural styles include the pipes-and-filters architectures, the broker architectures, the peer-to-peer architectures, and the message-oriented architectures.

Using Styles

Most applications use a mix of these architectural styles.

What

In software development, there are certain problems that recur in a certain context.

After repeated attempts at solving such problems, better solutions are discovered and refined over time. These solutions are known as design patterns, **a term popularized by the seminal book Design Patterns: Elements of Reusable Object-Oriented Software by the so-called "Gang of Four"** (GoF) book written by Eric Gamma, Richard Helm, Ralph Johnson,and John Vlissides

Format

The common format to describe a pattern consists of the following components:

• Context: The situation or scenario where the design problem is encountered.
• Problem: The main difficulty to be resolved.
• Solution: The core of the solution. It is important to note that the solution presented only includes the most general details, which may need further refinement for a specific context.
• Anti-patterns (optional): Commonly used solutions, which are usually incorrect and/or inferior to the Design Pattern.
• Consequences (optional): Identifying the pros and cons of applying the pattern.
• Other useful information (optional): Code examples, known uses, other related patterns, etc.

What

Context

A certain classes should have no more than just one instance (e.g. the main controller class of the system). These single instances are commonly known as singletons.

Problem

A normal class can be instantiated multiple times by invoking the constructor.

Solution

Make the constructor of the singleton class private,  because a public constructor will allow others to instantiate the class at will. Provide a public class-level method to access the single instance.

Example:

Implementation

Here is the typical implementation of how the Singleton pattern is applied to a class:

class Logic {
    private static Logic theOne = null;

    private Logic() {
        ...
    }

    public static Logic getInstance() {
        if (theOne == null) {
            theOne = new Logic();
        }
        return theOne;
    }
}

Notes:

• The constructor is private, which prevents instantiation from outside the class.
• The single instance of the singleton class is maintained by a private class-level variable.
• Access to this object is provided by a public class-level operation getInstance() which instantiates a single copy of the singleton class when it is executed for the first time. Subsequent calls to this operation return the single instance of the class.

If Logic was not a Singleton class, an object is created like this:

Logic m = new Logic();

But now, the Logic object needs to be accessed like this:

Logic m = Logic.getInstance();

Evaluation

Pros:

• easy to apply
• effective in achieving its goal with minimal extra work
• provides an easy way to access the singleton object from anywhere in the code base

Cons:

• The singleton object acts like a global variable that increases coupling across the code base.
• In testing, it is difficult to replace Singleton objects with stubs (static methods cannot be overridden)
• In testing, singleton objects carry data from one test to another even when we want each test to be independent of the others.

Given there are some significant cons, it is recommended that you apply the Singleton pattern when, in addition to requiring only one instance of a class, there is a risk of creating multiple objects by mistake, and creating such multiple objects has real negative consequences.

What

Context

There is a group of similar entities that appears to be ‘occurrences’ (or ‘copies’) of the same thing, sharing lots of common information, but also differing in significant ways.

Problem

Representing the objects mentioned previously as a single class would be problematic because it results in duplication of data which can lead to inconsistencies in data (if some of the duplicates are not updated consistently).

📦 Take for example the problem of representing books in a library. Assume that there could be multiple copies of the same title, bearing the same ISBN number, but different serial numbers.

The above solution requires common information to be duplicated by all instances. This will not only waste storage space, but also creates a consistency problem. Suppose that after creating several copies of the same title, the librarian realized that the author name was wrongly spelt. To correct this mistake, the system needs to go through every copy of the same title to make the correction. Also, if a new copy of the title is added later on, the librarian (or the system) has to make sure that all information entered is the same as the existing copies to avoid inconsistency.

Anti-pattern

📦 Refer to the same Library example given above.

The design above segregates the common and unique information into a class hierarchy. Each book title is represented by a separate class with common data (i.e. Name, Author, ISBN) hard-coded in the class itself. This solution is problematic because each book title is represented as a class, resulting in thousands of classes (one for each title). Every time the library buys new books, the source code of the system will have to be updated with new classes.

Solution

Let a copy of an entity (e.g. a copy of a book)be represented by two objects instead of one, separating the common and unique information into two classes to avoid duplication.

📦 Given below is how the pattern is applied to the Library example:

📦 Here's a more generic example:

The general solution:

The << Abstraction >> class should hold all common information, and the unique information should be kept by the << Occurrence >> class. Note that ‘Abstraction’ and ‘Occurrence’ are not class names, but roles played by each class. Think of this diagram as a meta-model (i.e. a ‘model of a model’) of the BookTitle-BookCopy class diagram given above.

What

Context

Components need to access functionality deep inside other components.

📦 The UI component of a Library system might want to access functionality of the Book class contained inside the Logic component.

Problem

Access to the component should be allowed without exposing its internal details.  e.g. the UI component should access the functionality of the Logic component without knowing that it contained a Book class within it.

Solution

Include a Façade class that sits between the component internals and users of the component such that all access to the component happens through the Facade class.

📦 The following class diagram applies the Façade pattern to the Library System example. The LibraryLogic class is the Facade class.

What

Context

A system is required to execute a number of commands, each doing a different task. For example, a system might have to support Sort, List, Reset commands.

Problem

It is preferable that some part of the code executes these commands without having to know each command type.  e.g., there can be a CommandQueue object that is responsible for queuing commands and executing them without knowledge of what each command does.

Solution

The essential element of this pattern is to have a general << Command >> object that can be passed around, stored, executed, etc without knowing the type of command (i.e. via polymorphism).

Let us examine an example application of the pattern first:

📦 In the example solution below, the CommandCreator creates List, Sort, and Reset Command objects and adds them to the CommandQueue object. The CommandQueue object treats them all as Command objects and performs the execute/undo operation on each of them without knowledge of the specific Command type. When executed, each Command object will access the DataStore object to carry out its task. The Command class can also be an abstract class or an interface.

The general form of the solution is as follows.

The << Client >> creates a << ConcreteCommand >> object, and passes it to the << Invoker >>. The << Invoker >> object treats all commands as a general << Command >> type. << Invoker >> issues a request by calling execute() on the command. If a command is undoable, << ConcreteCommand >> will store the state for undoing the command prior to invoking execute(). In addition, the << ConcreteCommand >> object may have to be linked to any << Receiver >> of the command ( ?) before it is passed to the << Invoker >>. Note that an application of the command pattern does not have to follow the structure given above.

What

Context

Most applications support storage/retrieval of information, displaying of information to the user (often via multiple UIs having different formats), and changing stored information based on external inputs.

Problem

To reduce coupling resulting from the interlinked nature of the features described above.

Solution

To decouple data, presentation, and control logic of an application by separating them into three different components: Model, View and Controller.

• View: Displays data, interacts with the user, and pulls data from the model if necessary.
• Controller: Detects UI events such as mouse clicks, button pushes and takes follow up action. Updates/changes the model/view when necessary.
• Model: Stores and maintains data. Updates views if necessary.

The relationship between the components can be observed in the diagram below. Typically, the UI is the combination of view and controller.

📦 Given below is a concrete example of MVC applied to a student management system. In this scenario, the user is retrieving data of one student.

In the diagram above, when the user clicks on a button using the UI, the ‘click’ event is caught and handled by the UiController.

Note that in a simple UI where there’s only one view, Controller and View can be combined as one class.

There are many variations of the MVC model used in different domains. For example, the one used in a desktop GUI could be different from the one used in a Web application.

What

📦 Here is a scenario from the a student management system where the user is adding a new student to the system.

Now, assume the system has two additional views used in parallel by different users:

• StudentListUi: that accesses a list of students and
• StudentStatsUi: that generates statistics of current students.

When a student is added to the database using NewStudentUi shown above, both StudentListUi and StudentStatsUi should get updated automatically, as shown below.

However, the StudentList object has no knowledge about StudentListUi and StudentStatsUi (note the direction of the navigability) and has no way to inform those objects. This is an example of the type of problem addressed by the Observer pattern.

Context

An object (possibly, more than one) is interested to get notified when a change happens to another object. That is, some objects want to ‘observe’ another object.

Problem

The ‘observed’ object does not want to be coupled to objects that are ‘observing’ it.

Solution

Force the communication through an interface known to both parties.

StudentList studentList = new StudentList();
StudentListUi listUi = new StudentListUi();
StudentStatusUi statusUi = new StudentStatsUi();

studentList.addUi(listUi);
studentList.addUi(statusUi);

//StudentList class
public void addUi(Observer o) {
    observerList.add(o);
}

//StudentList class
public void notifyUIs() {
    for(Observer o: observerList) //for each observer in the list
        o.update();
}

//StudentListUI class
public void update() {
    //refresh UI by pulling data from StudentList
}

Here is the generic description of the observer pattern:

• << Observer >> is an interface: any class that implements it can observe an << Observable >>. Any number of << Observer >> objects can observe (i.e. listen to changes of) the << Observable >> object.
• The << Observable >> maintains a list of << Observer >> objects. addObserver(Observer) operation adds a new << Observer >> to the list of << Observer >>s.
• Whenever there is a change in the << Observable >>, the notifyObservers() operation is called that will call the update() operation of all << Observer >>s in the list.

In a GUI application, how is the Controller notified when the “save” button is clicked? UI frameworks such as JavaFX has inbuilt support for the Observer pattern.

Combining Design Patterns

Design patterns are usually embedded in a larger design and sometimes applied in combination with other design patterns.

📦 Let us look at a case study that shows how design patterns are used in the design of a class structure for a Stock Inventory System (SIS) for a shop. The shop sells appliances, and accessories for the appliances. SIS simply stores information about each item in the store.

Use Cases:

• Create a new item
• View information about an item
• Modify information about an item
• View all available accessories for a given appliance
• List all items in the store

SIS can be accessed using multiple terminals. Shop assistants use their own terminals to access SIS, while the shop manager’s terminal continuously displays a list of all items in store. In the future, it is expected that suppliers of items use their own applications to connect to SIS to get real-time information about current stock status. User authentication is not required for the current version, but may be required in the future.

A step by step explanation of the design is given below. Note that this is one out of many possible designs. Design patterns are also applied where appropriate.

A StockItem can be an Appliance or an Accessory.

To track that each Accessory is associated with the correct Appliance, consider the following alternative class structures.

The third one seems more appropriate (the second one is suitable if accessories can have accessories). Next, consider between keeping a list of Appliances, and a list of StockItems. Which is more appropriate?

The latter seems more suitable because it can handle both appliances and accessories the same way. Next, an abstraction occurrence pattern is applied to keep track of StockItems.

Note the inclusion of navigabilities. Here’s a sample object diagram based on the class model created thus far.

Next, apply the façade pattern to shield the SIS internals from the UI.

As UI consists of multiple views, the MVC pattern is applied here.

Some views need to be updated when the data change; apply the Observer pattern here.

In addition, the Singleton pattern can be applied to the façade class.

Other Design Patterns

The most famous source of design patterns is the "Gang of Four" (GoF) book which contains 23 design patterns divided into three categories:

• Creational: About object creation. They separate the operation of an application from how its objects are created.
  • Abstract Factory, Builder, Factory Method, Prototype, Singleton
• Structural: About the composition of objects into larger structures while catering for future extension in structure.
  • Adapter, Bridge, Composite, Decorator, Façade, Flyweight, Proxy
• Behavioral: Defining how objects interact and how responsibility is distributed among them.
  • Chain of Responsibility, Command, Interpreter, Template Method, Iterator, Mediator, Memento, Observer, State, Strategy, Visitor

Using Design Patterns

Design pattern provides a high-level vocabulary to talk about design.

Knowing more patterns is a way to become more ‘experienced’. Aim to learn at least the context and the problem of patterns  so that when you encounter those problems you know where to look for a solution.

Some patterns are domain-specific  e.g. patterns for distributed applications, some are created in-house  e.g. patterns in the company/project and some can be self-created  e.g. from past experience.

Be careful not to overuse patterns. Do not throw patterns at a problem at every opportunity. Patterns come with overhead such as adding more classes or increasing the levels of abstraction. Use them only when they are needed. Before applying a pattern, make sure that:

• there is substantial improvement in the design, not just superficial.
• the associated tradeoffs are carefully considered. There are times when a design pattern is not appropriate (or an overkill).

Other Types of Patterns

The notion of capturing design ideas as "patterns" is usually attributed to Christopher Alexander. He is a building architect noted for his theories about design. His book Timeless way of building talks about "design patterns" for constructing buildings.

Here is a sample pattern from that book:

When a room has a window with a view, the window becomes a focal point: people are attracted to the window and want to look through it. The furniture in the room creates a second focal point: everyone is attracted toward whatever point the furniture aims them at (usually the center of the room or a TV). This makes people feel uncomfortable. They want to look out the window, and toward the other focus at the same time. If you rearrange the furniture, so that its focal point becomes the window, then everyone will suddenly notice that the room is much more “comfortable”

Apparently, patterns and anti-patterns are found in the field of building architecture. This is because they are general concepts applicable to any domain, not just software design. In software engineering, there are many general types of patterns: Analysis patterns, Design patterns, Testing patterns, Architectural patterns, Project management patterns, and so on.

In fact, the abstraction occurrence pattern is more of an analysis pattern than a design pattern, while MVC is more of an architectural pattern.

New patterns can be created too. If a common problem needs to be solved frequently that leads to a non-obvious and better solution, it can be formulated as a pattern so that it can be reused by others. However, don’t reinvent the wheel; the pattern might already exist.

Design Patterns vs Design Principles

Design principles have varying degrees of formality – rules, opinions, rules of thumb, observations, and axioms. Compared to design patterns, principles are more general, have wider applicability, with correspondingly greater overlap among them.

Multi-Level Design

In a smaller system, design of the entire system can be shown in one place.

📦 This class diagram of se-edu/addressbook-level3 depicts the design of the entire software.

Design of bigger systems needs to be done/shown at multiple levels.

📦 This architecture diagram of se-edu/addressbook-level4 depicts the high-level design of the software.

Here are examples of lower level designs of some components of the same software:

---

---

---

Top-Down and Bottom-Up Design

Multi-level design can be done in a top-down manner, bottom-up manner, or as a mix.

• Top-down: Design the high-level design first and flesh out the lower levels later. This is especially useful when designing big and novel systems where the high-level design needs to be stable before lower levels can be designed.
• Bottom-up: Design lower level components first and put them together to create the higher-level systems later. This is not usually scalable for bigger systems. One instance where this approach might work is when designing a variations of an existing system or re-purposing existing components to build a new system.
• Mix: Design the top levels using the top-down approach but switch to a bottom-up approach when designing the bottom levels.

Agile Design

Agile design can be contrasted with full upfront design in the following way:

Agile designs are emergent, they’re not defined up front. Your overall system design will emerge over time, evolving to fulfill new requirements and take advantage of new technologies as appropriate. Although you will often do some initial architectural modeling at the very beginning of a project, this will be just enough to get your team going. This approach does not produce a fully documented set of models in place before you may begin coding. _{-- adapted from agilemodeling.com}

What

Professional software engineers often write code using Integrated Development Environments (IDEs). IDEs support all development-related work within the same tool.

An IDE generally consists of:

• A source code editor that includes features such as syntax coloring, auto-completion, easy code navigation, error highlighting, and code-snippet generation.
• A compiler and/or an interpreter (together with other build automation support) that facilitates the compilation/linking/running/deployment of a program.
• A debugger that allows the developer to execute the program one step at a time to observe the run-time behavior in order to locate bugs.
• Other tools that aid various aspects of coding e.g. support for automated testing, drag-and-drop construction of UI components, version management support, simulation of the target runtime platform, and modeling support.

Examples of popular IDEs:

• Java: Eclipse, Intellij IDEA, NetBeans
• C#, C++: Visual Studio
• Swift: XCode
• Python: PyCharm

Some Web-based IDEs have appeared in recent times too e.g., Amazon's Cloud9 IDE.

Some experienced developers, in particular those with a UNIX background, prefer lightweight yet powerful text editors with scripting capabilities (e.g. Emacs) over heavier IDEs.

What

Debugging is the process of discovering defects in the program. Here are some approaches to debugging:

• 👎 By inserting temporary print statements: This is an ad-hoc approach in which print statements are inserted in the program to print information relevant to debugging, such as variable values. e.g. Exiting process() method, x is 5.347. This approach is not recommended due to these reasons.

  • Incurs extra effort when inserting and removing the print statements.
  • Unnecessary program modifications increases the risk of introducing errors into the program.
  • These print statements, if not promptly removed, may even appear unexpectedly in the production version.

• 👎 By manually tracing through the code: Otherwise known as ‘eye-balling’, this approach doesn't have the cons of the previous approach, but it too is not recommended (other than as a 'quick try') due to these reasons:

  • It is difficult, time consuming, and error-prone technique.
  • If you didn't spot the error while writing code, you might not spot the error when reading code too.

• 👍 Using a debugger: A debugger tool allows you to pause the execution, then step through one statement at a time while examining the internal state if necessary. Most IDEs come with an inbuilt debugger. This is the recommended approach for debugging.

Basic

Always code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live. _{-- Martin Golding}

Production code needs to be of high quality. Given how the world is becoming increasingly dependent of software, poor quality code is something we cannot afford to tolerate.

Introduction

Programs should be written and polished until they acquire publication quality. _{--Niklaus Wirth}

Among various dimensions of code quality, such as run-time efficiency, security, and robustness, one of the most important is understandability. This is because in any non-trivial software project, code needs to be read, understood, and modified by other developers later on. Even if we do not intend to pass the code to someone else, code quality is still important because we all become 'strangers' to our own code someday.

int subsidy() {
    int subsidy;
    if (!age) {
        if (!sub) {
            if (!notFullTime) {
                subsidy = 500;
            } else {
                subsidy = 250;
            }
        } else {
            subsidy = 250;
        }
    } else {
        subsidy = -1;
    }
    return subsidy;
}

int calculateSubsidy() {
    int subsidy;
    if (isSenior) {
        subsidy = REJECT_SENIOR;
    } else if (isAlreadySubsidised) {
        subsidy = SUBSIDISED_SUBSIDY;
    } else if (isPartTime) {
        subsidy = FULLTIME_SUBSIDY * RATIO;
    } else {
        subsidy = FULLTIME_SUBSIDY;
    }
    return subsidy;
}

Basic

Intermediate

Advanced

Introduction

One essential way to improve code quality is to follow a consistent style. That is why software engineers follow a strict coding standard (aka style guide).

The aim of a coding standard is to make the entire code base look like it was written by one person. A coding standard is usually specific to a programming language and specifies guidelines such as the location of opening and closing braces, indentation styles and naming styles (e.g. whether to use Hungarian style, Pascal casing, Camel casing, etc.). It is important that the whole team/company use the same coding standard and that standard is not generally inconsistent with typical industry practices. If a company's coding standards is very different from what is used typically in the industry, new recruits will take longer to get used to the company's coding style.

Basic

Go through the provided Java coding standard and learn the basic style rules.

Intermediate

Go through the provided Java coding standard and learn the intermediate style rules.

Introduction

Proper naming improves the readability. It also reduces bugs caused by ambiguities regarding the intent of a variable or a method.

There are only two hard things in Computer Science: cache invalidation and naming things. _{-- Phil Karlton}

Basic

Intermediate

Introduction

It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them.

Basic

Intermediate

Introduction

Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. _{--Steve McConnell, Author of Clean Code}

Some think commenting heavily increases the 'code quality'. This is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.

Basic

Intermediate

What

The first version of the code you write may not be of production quality. It is OK to first concentrate on making the code work, rather than worry over the quality of the code, as long as you improve the quality later. This process of improving a program's internal structure in small steps without modifying its external behavior is called refactoring.

• Refactoring is not rewriting: Discarding poorly-written code entirely and re-writing it from scratch is not refactoring because refactoring needs to be done in small steps.
• Refactoring is not bug fixing: By definition, refactoring is different from bug fixing or any other modifications that alter the external behavior (e.g. adding a feature) of the component in concern.

Given below are two common refactorings (taken from refactoring-catalog ).

if (isSpecialDeal()) {
    total = price * 0.95;
    send();
} else {
    total = price * 0.98;
    send();
}

if (isSpecialDeal()){
    total = price * 0.95;
} else {
    total = price * 0.98;
}
send();

void printOwing() {
    printBanner();

    //print details
    System.out.println("name:	" + name);
    System.out.println("amount	" + getOutstanding());
}

void printOwing() {
    printBanner();
    printDetails(getOutstanding());
}

void printDetails (double outstanding) {
    System.out.println("name:	" + name);
    System.out.println("amount	" + outstanding);
}

How

Given below are some more commonly used refactorings. A more comprehensive list is available at refactoring-catalog .

1. Consolidate Conditional Expression
2. Decompose Conditional
3. Inline Method
4. Remove Double Negative
5. Replace Magic Number with Symbolic Constant
6. Replace Nested Conditional with Guard Clauses
7. Replace Parameter with Explicit Methods
8. Reverse Conditional
9. Split Loop
10. Split Temporary Variable

When

We know that it is important to refactor frequently so as to avoid the accumulation of ‘messy’ code which might get out of control. But how much refactoring is too much refactoring? It is too much refactoring when the benefits no longer justify the cost. The costs and the benefits depend on the context. That is why some refactorings are ‘opposites’ of each other (e.g. extract method vs inline method).

What

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

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

2. 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 need to be included in the documentation, as code (and code comments) can also serve as a complementary source of information.

What

When writing project documents, a top-down breadth-first explanation is easier to understand than a bottom-up one.

Why

The main advantage of the top-down approach is that the document is structured like an upside down tree (root at the top) and the reader can travel down a path she is interested in until she reaches the component she is interested to learn in-depth, without having to read the entire document or understand the whole system.

How

What

Technical documents exist to help others understand technical details. Therefore, it is not enough for the documentation to be accurate and comprehensive, it should also be comprehensible too.

How

Here are some tips on writing effective documentation.

• Use plenty of diagrams: It is not enough to explain something in words; complement it with visual illustrations (e.g. a UML diagram).
• Use plenty of examples: When explaining algorithms, show a running example to illustrate each step of the algorithm, in parallel to worded explanations.
• Use simple and direct explanations: Convoluted explanations and fancy words will annoy readers. Avoid long sentences.
• Get rid of statements that do not add value: For example, 'We made sure our system works perfectly' (who didn't?), 'Component X has its own responsibilities' (of course it has!).
• It is not a good idea to have separate sections for each type of artifact, such as 'use cases', 'sequence diagrams', 'activity diagrams', etc. Such a structure, coupled with the indiscriminate inclusion of diagrams without justifying their need, indicates a failure to understand the purpose of documentation. Include diagrams when they are needed to explain something. If you want to provide additional diagrams for completeness' sake, include them in the appendix as a reference.

What

Aim for 'just enough' developer documentation.

• Writing and maintaining developer documents is an overhead. You should try to minimize that overhead.
• If the readers are developers who will eventually read the code, the documentation should complement the code and should provide only just enough guidance to get started.

How

Anything that is already clear in the code need not be described in words. Instead, focus on providing higher level information that is not readily visible in the code or comments.

Refrain from duplicating chunks or text. When describing several similar algorithms/designs/APIs, etc., do not simply duplicate large chunks of text. Instead, describe the similarity in one place and emphasize only the differences in other places. It is very annoying to see pages and pages of similar text without any indication as to how they differ from each other.

What

Javadoc is a tool for generating API documentation in HTML format from doc comments in source. In addition, modern IDEs use JavaDoc comments to generate explanatory tool tips.

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param url an absolute URL giving the base location of the image
 * @param name the location of the image, relative to the url argument
 * @return the image at the specified URL
 * @see Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

What

Markdown is a lightweight markup language with plain text formatting syntax.

What

AsciiDoc is similar to Markdown but has more powerful (but also more complex) syntax.

What

Well-written applications include error-handling code that allows them to recover gracefully from unexpected errors. When an error occurs, the application may need to request user intervention, or it may be able to recover on its own. In extreme cases, the application may log the user off or shut down the system. --_(source)

What

Exceptions are used to deal with 'unusual' but not entirely unexpected situations that the program might encounter at run time.

How

Most languages allow a method to encapsulate the unusual situation in an Exception object and 'throw'/'raise' that object so that another piece of code can 'catch' it and deal with it. This is especially useful when code segment that encountered the unusual situation does not know how to deal with it.

Exception objects can propagate up the method/function call hierarchy until it is dealt with. Usually, an exception thrown by a method is caught by the caller method. If the called method does not know how to deal with the exception it caught, it can throw/raise the Exception object to its own caller. If none of the callers is prepared to deal with the exception, the exceptions can propagate through the method call stack until it is received by the main method and thrown to the runtime, thus halting the system.

📦 In the code given below, processArray can potentially throw an InvalidInputException. Because of that, processInput method invokes processArray method inside a try{ } block and has a catch{ } block to specify what to do if the exception is actually thrown.

📦 In the code given below, process_array function can potentially raise a ValueError exception. Because of that, process_input function invokes process_array function inside a try clause and has a except clause to specify what to do if the exception is actually raised.

---

Advantages of exception handling in this way:

• The ability to propagate error information through the call stack.
• The separation of code that deals with 'unusual' situations from the code that does the 'usual' work.

When

In general, use exceptions only for 'unusual' conditions. Use normal return statements to pass control to the caller for conditions that are 'normal'.

What

Assertions are used to define assumptions about the program state so that the runtime can verify them. An assertion failure indicates a possible bug in the code because the code has resulted in a program state that violates an assumption about how the code should behave.

If the runtime detects an assertion failure, it typically take some drastic action such as terminating the execution with an error message. This is because an assertion failure indicates a possible bug and the sooner the execution stops, the safer it is.

int timeout = Config.getTimeout(); 

How

Use the assert keyword to define assertions.

x = getX();
assert x == 0 : "x should be 0";
...

Assertions can be disabled without modifying the code.

When

It is recommended that assertions be used liberally in the code. Their impact on performance is considered low and worth the additional safety they provide.

Do not use assertions to do work because assertions can be disabled. If not, your program will stop working when assertions are not enabled.

...
assert writeFile() : "File writing is supposed to return true";

Assertions are suitable for verifying assumptions about Internal Invariants, Control-Flow Invariants, Preconditions, Postconditions, and Class Invariants. Refer to [Programming with Assertions (second half)] to learn more.

Exceptions and assertions are two complementary ways of handling errors in software but they serve different purposes. Therefore, both assertions and exceptions should be used in code.

• The raising of an exception indicates an unusual condition created by the user  (e.g. user inputs an unacceptable input) or the environment  (e.g., a file needed for the program is missing).
• An assertion failure indicates the programmer made a mistake in the code  (e.g., a null value is returned from a method that is not supposed to return null under any circumstances).

What

Logging is the deliberate recording of certain information during a program execution for future reference. Logs are typically written to a log file but it is also possible to log information in other ways  e.g. into a database or a remote server.

Logging can be useful for troubleshooting problems. A good logging system records some system information regularly. When bad things happen to a system  e.g. an unanticipated failure, their associated log files may provide indications of what went wrong and action can then be taken to prevent it from happening again.

How

Most programming environments come with logging systems that allow sophisticated forms of logging. They have features such as the ability to enable and disable logging easily or to change the logging intensity.

import java.util.logging.*;

private static Logger logger = Logger.getLogger("Foo");

// log a message at INFO level
logger.log(Level.INFO, "going to start processing");
//...
processInput();
if(error){
    //log a message at WARNING level
    logger.log(Level.WARNING, "processing error", ex);
}
//...
logger.log(Level.INFO, "end of processing");

What

A defensive programmer codes under the assumption "if we leave room for things to go wrong, they will go wrong". Therefore, a defensive programmer proactively tries to eliminate any room for things to go wrong.

class MainApp{
    Config config;
    
    /** Returns the config object */
    Config getConfig(){
        return config;
    }
}

    /** Returns a copy of the config object */
    Config getConfig(){
        return config.copy(); //return a defensive copy
    }

Enforcing Compulsory Associations

Consider two classes, Account and Guarantor, with an association as shown in the following diagram:

Example:

Here, the association is compulsory i.e. an Account object should always be linked to a Guarantor. One way to implement this is to simply use a reference variable, like this:

class Account {
    Guarantor guarantor;

    void setGuarantor(Guarantor g) {
        guarantor = g;
    }
}

However, what if someone else used the Account class like this?

Account a = new Account();
a.setGuarantor(null);

This results in an Account without a Guarantor! In a real banking system, this could have serious consequences! The code here did not try to prevent such a thing from happening. We can make the code more defensive by proactively enforcing the multiplicity constraint, like this:

class Account {
    private Guarantor guarantor;

    public Account(Guarantor g){
        if (g == null) {
            stopSystemWithMessage("multiplicity violated. Null Guarantor");
        }
        guarantor = g;
    }
    public void setGuarantor (Guarantor g){
        if (g == null) {
            stopSystemWithMessage("multiplicity violated. Null Guarantor");
        }
        guarantor = g;
    }
    …
}

Enforcing 1-to-1 Associations

Consider the association given below. A defensive implementation requires to ensure a MinedCell cannot exist without a Mine and vice versa which requires simultaneous object creation. However, Java can only create one object at a time. Given below are two alternatives implementations, both of which violate the multiplicity for a short period of time.

Option 1:

class MinedCell {
    private Mine mine;

    public MinedCell(Mine m){
        if (m == null) {
            showError();
        }
        mine = m;
    }
    …
}

Option 1 forces us to keep a Mine without a MinedCell (until the MinedCell is created).

Option 2:

class MinedCell {
    private Mine mine;

    public MinedCell(){
        mine = new Mine();
    }
    …
}

Option 2 is more defensive because the Mine is immediately linked to a MinedCell.

Enforcing Referential Integrity

A bidirectional association in the design (shown in (a)) is usually emulated at code level using two variables (as shown in (b)).

class Man {
    Woman girlfriend;

    void setGirlfriend(Woman w) {
        girlfriend = w;
    }
    …
}

class Woman {
    Man boyfriend;

    void setBoyfriend(Man m) {
        boyfriend = m;
    }
}

The two classes are meant to be used as follows:

Woman jean;
Man james;
…
james.setGirlfriend(jean);
jean.setBoyfriend(james);

Suppose the two classes were used this instead:

Woman jean; Man james, yong;
…
james.setGirlfriend(jean);  
jean.setBoyfriend(yong);  

Now James' girlfriend is Jean, while Jean's boyfriend is not James. This situation results as the code was not defensive enough to stop this "love triangle". In such a situation, we say that the referential integrity has been violated. It simply means there is an inconsistency in object references.

One way to prevent this situation is to implement the two classes as shown below. Note how the referential integrity is maintained.

public class Woman {
    private Man boyfriend;

    public void setBoyfriend(Man m) {
        if(boyfriend == m){
            return;
        }
        if (boyfriend != null) {
            boyfriend.breakUp();
        }
        boyfriend = m;
        m.setGirlfriend(this);
    }

    public void breakUp() {
        boyfriend = null;
    }   
    ...
}

public class Man{
    private Woman girlfriend;

    public void setGirlfriend(Woman w) {
        if(girlfriend == w){
            return;
        }
        if (girlfriend != null) {
            girlfriend.breakUp();
        }
        girlfriend = w;
        w.setBoyfriend(this);
    }
    public void breakUp() {
        girlfriend = null;
    }  
   ...
}

When the code james.setGirlfriend(jean) is executed, the code ensures that james break up with any current girlfriend before he accepts jean as the girlfriend. Furthermore, the code ensures that jean breaks up with any existing boyfriends and accepts james as the boyfriend.

When

It is not necessary to be 100% defensive all the time. While defensive code may be less prone to be misused or abused, such code can also be more complicated and slower to run.

The suitable degree of defensiveness depends on many factors such as:

• How critical is the system?
• Will the code be used by programmers other than the author?
• The level of programming language support for defensive programming
• The overhead of being defensive

Design by Contract

Design by contract (DbC) is an approach for designing software that requires defining formal, precise and verifiable interface specifications for software components.

Suppose an operation is implemented with the behavior specified precisely in the API (preconditions, post conditions, exceptions etc.). When following the defensive approach, the code should first check if the preconditions have been met. Typically, exceptions are thrown if preconditions are violated. In contrast, the Design-by-Contract (DbC) approach to coding assumes that it is the responsibility of the caller to ensure all preconditions are met. The operation will honor the contract only if the preconditions have been met. If any of them have not been met, the behavior of the operation is "unspecified".

Languages such as Eiffel have native support for DbC. For example, preconditions of an operation can be specified in Eiffel and the language runtime will check precondition violations without the need to do it explicitly in the code. To follow the DbC approach in languages such as Java and C++ where there is no built-in DbC support, assertions can be used to confirm pre-conditions.

What

Combining parts of a software product to form a whole is called integration. It is also one of the most troublesome tasks and it rarely goes smoothly.

'Late and One Time' vs 'Early and Frequent'

In terms of timing and frequency, there are two general approaches to integration: late and one-time, early and frequent.

Late and one-time: wait till all components are completed and integrate all finished components near the end of the project.

Early and frequent: integrate early and evolve each part in parallel, in small steps, re-integrating frequently.

Big-Bang vs Incremental Integration

Big-bang integration: integrate all components at the same time.

Incremental integration: integrate few components at a time. This approach is better than the big-bang integration because it surfaces integration problems in a more manageable way.

Top-Down vs Bottom-Up Integration

Based on the order in which components are integrated, incremental integration can be done in three ways.

Top-down integration: higher-level components are integrated before bringing in the lower-level components. One advantage of this approach is that higher-level problems can be discovered early. One disadvantage is that this requires the use of stubs in place of lower level components until the real lower-level components are integrated to the system. Otherwise, higher-level components cannot function as they depend on lower level ones.

Bottom-up integration: the reverse of top-down integration. Note that when integrating lower level components, drivers may be needed to test the integrated components  because the UI may not be integrated yet, just like top-down integration needs stubs.

Sandwich integration: a mix of the top-down and the bottom-up approaches. The idea is to do both top-down and bottom-up so as to 'meet' in the middle.

What

Build automation tools automate the steps of the build process, usually by means of build scripts.

In a non-trivial project, building a product from source code can be a complex multi-step process.  For example, it can include steps such as to pull code from the revision control system, compile, link, run automated tests, automatically update release documents (e.g. build number), package into a distributable, push to repo, deploy to a server, delete temporary files created during building/testing, email developers of the new build, and so on. Furthermore, this build process can be done ‘on demand’, it can be scheduled (e.g. every day at midnight) or it can be triggered by various events (e.g. triggered by a code push to the revision control system).

Some of these build steps such as to compile, link and package are already automated in most modern IDEs.  For example, several steps happen automatically when the ‘build’ button of the IDE is clicked. Some IDEs even allow customization to this build process to some extent.

However, most big projects use specialized build tools to automate complex build processes.

Some build tools also serve as dependency management tools. Modern software projects often depend on third party libraries that evolve constantly. That means developers need to download the correct version of the required libraries and update them regularly. Therefore, dependency management is an important part of build automation. Dependency Management tools can automate that aspect of a project.

Continuous Integration and Continuous Deployment

An extreme application of build automation is called continuous integration (CI) in which integration, building, and testing happens automatically after each code change.

A natural extension of CI is Continuous Deployment (CD) where the changes are not only integrated continuously, but also deployed to end-users at the same time.

What

Reuse is a major theme in software engineering practices. By reusing tried-and-tested components, the robustness of a new software system can be enhanced while reducing the manpower and time requirement. Reusable components come in many forms; it can be reusing a piece of code, a subsystem, or a whole software.

When

While you may be tempted to use many libraries/frameworks/platform that seem to crop up on a regular basis and promise to bring great benefits, note that there are costs associated with reuse. Here are some:

• The reused code may be an overkill (think using a sledgehammer to crack a nut) increasing the size of, or/and degrading the performance of, your software.
• The reused software may not be mature/stable enough to be used in an important product. That means the software can change drastically and rapidly, possibly in ways that break your software.
• Non-mature software has the risk of dying off as fast as they emerged, leaving you with a dependency that is no longer maintained.
• The license of the reused software (or its dependencies) restrict how you can use/develop your software.
• The reused software might have bugs, missing features, or security vulnerabilities that are important to your product but not so important to the maintainers of that software, which means those flaws will not get fixed as fast as you need them to.
• Malicious code can sneak into your product via compromised dependencies.

What

An Application Programming Interface (API) specifies the interface through which other programs can interact with a software component. It is a contract between the component and its clients.

When developing large systems, if you define the API of each components early, the development team can develop the components in parallel  because the future behavior of the other components are now more predictable.

Designing APIs

An API should be well-designed (i.e. should cater for the needs of its users) and well-documented.

When we write software consisting of multiple components, we need to define the API of each component.

One approach is to let the API emerge and evolve over time as we write code.

Another approach is to define the API up-front. Doing so allows us to develop the components in parallel.

We can use UML sequence diagrams to analyze the required interactions between components in order to discover the required API. Given below is an example.

Example:

As we analyze the interactions between components using sequence diagrams, we discover the API of those components. For example, the diagram above tells us that the MSLogic component API should have the methods:

• new()
• getWidth:int
• getHeight():int
• getRemainingMineCount():int

More details can be included to increase the precision of the method definitions before coding. Such precision is important to avoid misunderstandings between the developer of the class and developers of other classes that interact with this class.

• Operation: newGame(): void
• Description: Generates a new WxH minefield with M mines. Any existing minefield will be overwritten.
• Preconditions: None
• Postconditions: A new minefield is created. Game state is READY.

Preconditions are the conditions that must be true before calling this operation. Postconditions describe the system after the operation is complete. Note that post conditions do not say what happens during the operation. Here is another example:

• Operation: clearCellAt(int x, int y): void
• Description: Records the cell at x,y as cleared.
• Parameters: x, y coordinates of the cell
• Preconditions: game state is READY or IN_PLAY. x and y are in 0..(H-1) and 0..(W-1), respectively.
• Postconditions: Cell at x,y changes state to ZERO, ONE, TWO, THREE, …, EIGHT, or INCORRECTLY_CLEARED. Game state changes to IN_PLAY, WON or LOST as appropriate.

What

A library is a collection of modular code that is general and can be used by other programs.

How

These are the typical steps required to use a library.

1. Read the documentation to confirm that its functionality fits your needs
2. Check the license to confirm that it allows reuse in the way you plan to reuse it. For example, some libraries might allow non-commercial use only.
3. Download the library and make it accessible to your project. Alternatively, you can configure your dependency management tool to do it for you.
4. Call the library API from your code where you need to use the library functionality.

What

The overall structure and execution flow of a specific category of software systems can be very similar. The similarity is an opportunity to reuse at a high scale.

A software framework is a reusable implementation of a software (or part thereof) providing generic functionality that can be selectively customized to produce a specific application.

Some frameworks provide a complete implementation of a default behavior which makes them immediately usable.

A framework facilitates the adaptation and customization of some desired functionality.

Some frameworks cover only a specific components or an aspect.

Frameworks vs Libraries

Although both frameworks and libraries are reuse mechanisms, there are notable differences:

• Libraries are meant to be used ‘as is’ while frameworks are meant to be customized/extended.  e.g., writing plugins for Eclipse so that it can be used as an IDE for different languages (C++, PHP, etc.), adding modules and themes to Drupal, and adding test cases to JUnit.

• Your code calls the library code while the framework code calls your code. Frameworks use a technique called inversion of control, aka the “Hollywood principle” (i.e. don’t call us, we’ll call you!). That is, you write code that will be called by the framework,  e.g. writing test methods that will be called by the JUnit framework. In the case of libraries, your code calls libraries.

What

A platform provides a runtime environment for applications. A platform is often bundled with various libraries, tools, frameworks, and technologies in addition to a runtime environment but the defining characteristic of a software platform is the presence of a runtime environment.

What

Cloud computing is the delivery of computing as a service over the network, rather than a product running on a local machine. This means the actual hardware and software is located at a remote location, typically, at a large server farm, while users access them over the network. Maintenance of the hardware and software is managed by the cloud provider while users typically pay for only the amount of services they use. This model is similar to the consumption of electricity; the power company manages the power plant, while the consumers pay them only for the electricity used. The cloud computing model optimizes hardware and software utilization and reduces the cost to consumers. Furthermore, users can scale up/down their utilization at will without having to upgrade their hardware and software. The traditional non-cloud model of computing is similar to everyone buying their own generators to create electricity for their own use.

Iaas, PaaS, and SaaS

_{source:https://commons.wikimedia.org}

Cloud computing can deliver computing services at three levels:

1. Infrastructure as a service (IaaS) delivers computer infrastructure as a service. For example, a user can deploy virtual servers on the cloud instead of buying physical hardware and installing server software on them. Another example would be a customer using storage space on the cloud for off-site storage of data.  Rackspace is an example of an IaaS cloud provider. Amazon Elastic Compute Cloud (Amazon EC2) is another one.

2. Platform as a service (PaaS) provides a platform on which developers can build applications. Developers do not have to worry about infrastructure issues such as deploying servers or load balancing as is required when using IaaS. Those aspects are automatically taken care of by the platform. The price to pay is reduced flexibility; applications written on PaaS are limited to facilities provided by the platform.  A PaaS example is the Google App Engine where developers can build applications using Java, Python, PHP, or Go whereas Amazon EC2 allows users to deploy application written in any language on their virtual servers.

3. Software as a service (SaaS) allows applications to be accessed over the network instead of installing them on a local machine.  For example, Google Docs is an SaaS word processing software, while Microsoft Word is a traditional word processing software.

What

Software Quality Assurance (QA) is the process of ensuring that the software being built has the required levels of quality.

While testing is the most common activity used in QA, there are other complementary techniques such as static analysis, code reviews, and formal verification.

Validation vs Verification

Quality Assurance = Validation + Verification

QA involves checking two aspects:

1. Validation: are we building the right system i.e., are the requirements correct?
2. Verification: are we building the system right i.e., are the requirements implemented correctly?

Whether something belongs under validation or verification is not that important. What is more important is both are done, instead of limiting to verification (i.e., remember that the requirements can be wrong too).

What

Code review is the systematic examination code with the intention of finding where the code can be improved.

Reviews can be done in various forms. Some examples below:

• In pair programming

  • As pair programming involves two programmers working on the same code at the same time, there is an implicit review of the code by the other member of the pair.

• Pull Request reviews

  • Project Management Platforms such as GitHub and BitBucket allows the new code to be proposed as Pull Requests and provides the ability for others to review the code in the PR.

• Formal inspections

  • Inspections involve a group of people systematically examining a project artifacts to discover defects. Members of the inspection team play various roles during the process, such as:

    • the author - the creator of the artifact
    • the moderator - the planner and executor of the inspection meeting
    • the secretary - the recorder of the findings of the inspection
    • the inspector/reviewer - the one who inspects/reviews the artifact.

Advantages of code reviews over testing:

• It can detect functionality defects as well as other problems such as coding standard violations.
• Can verify non-code artifacts and incomplete code
• Do not require test drivers or stubs.

Disadvantages:

• It is a manual process and therefore, error prone.

What

Static analysis of code can find useful information such unused variables, unhandled exceptions, style errors, and statistics. Most modern IDEs come with some inbuilt static analysis capabilities. For example, an IDE can highlight unused variables as you type the code into the editor.

Higher-end static analyzer tools can perform for more complex analysis such as locating potential bugs, memory leaks, inefficient code structures etc.

Linters are a subset of static analyzers that specifically aim to locate areas where the code can be made 'cleaner'.

What

Formal verification uses mathematical techniques to prove the correctness of a program.

Advantages:

• Formal verification can be used to prove the absence of errors. In contrast, testing can only prove the presence of error, not their absence.

Disadvantages:

• It only proves the compliance with the specification, but not the actual utility of the software.
• It requires highly specialized notations and knowledge which makes it an expensive technique to administer. Therefore, formal verifications are more commonly used in safety-critical software such as flight control systems.

What

When testing, we execute a set of test cases. A test case specifies how to perform a test. At a minimum, it specifies the input to the software under test (SUT) and the expected behavior.

Test cases can be determined based on the specification, reviewing similar existing systems, or comparing to the past behavior of the SUT.

For each test case we do the following:

1. Feed the input to the SUT
2. Observe the actual output
3. Compare actual output with the expected output

A test case failure is a mismatch between the expected behavior and the actual behavior. A failure is caused by a defect (or a bug).

Testability

Testability is an indication of how easy it is to test an SUT. As testability depends a lot on the design and implementation. You should try to increase the testability when you design and implement a software. The higher the testability, the easier it is to achieve a better quality software.

What

Unit testing : testing individual units (methods, classes, subsystems, ...) to ensure each piece works correctly.

In OOP code, it is common to write one or more unit tests for each public method of a class.

class Foo{
    String read(){
        //...
    }
    
    void write(String input){
        //...
    }
    
}

class FooTest{
    
    @Test
    void read(){
        //a unit test for Foo#read() method
    }
    
    @Test
    void write_emptyInput_exceptionThrown(){
        //a unit tests for Foo#write(String) method
    }  
    
    @Test
    void write_normalInput_writtenCorrectly(){
        //another unit tests for Foo#write(String) method
    }
}

Stubs

A proper unit test requires the unit to be tested in isolation so that bugs in the dependencies cannot influence the test  i.e. bugs outside of the unit should not affect the unit tests.

Stubs can isolate the SUT from its dependencies.

class Logic {
    Storage s;

    Logic(Storage s) {
        this.s = s;
    }

    String getName(int index) {
        return "Name: " + s.getName(index);
    }
}

interface Storage {
    String getName(int index);
}

class DatabaseStorage implements Storage {

    @Override
    public String getName(int index) {
        return readValueFromDatabase(index);
    }

    private String readValueFromDatabase(int index) {
        // retrieve name from the database
    }
}

Logic logic = new Logic(new DatabaseStorage());
String name = logic.getName(23);

@Test
void getName() {
    Logic logic = new Logic(new DatabaseStorage());
    assertEquals("Name: John", logic.getName(5));
}

class StorageStub implements Storage {

    @Override
    public String getName(int index) {
        if(index == 5) {
            return "Adam";
        } else {
            throw new UnsupportedOperationException();
        }
    }
}

@Test
void getName() {
    Logic logic = new Logic(new StorageStub());
    assertEquals("Name: Adam", logic.getName(5));
}

In addition to Stubs, there are other type of replacements you can use during testing. E.g. Mocks, Fakes, Dummies, Spies.

What

Integration testing : testing whether different parts of the software work together (i.e. integrates) as expected. Integration tests aim to discover bugs in the 'glue code' related to how components interact with each other. These bugs are often the result of misunderstanding of what the parts are supposed to do vs what the parts are actually doing.

What

System testing: take the whole system and test it against the system specification.

System testing is typically done by a testing team (also called a QA team).

System test cases are based on the specified external behavior of the system. Sometimes, system tests go beyond the bounds defined in the specification. This is useful when testing that the system fails 'gracefully' having pushed beyond its limits.

Test case: load a web page that is too big
* Input: load a web page containing more than 5000 characters. 
* Expected behavior: abort the loading of the page and show a meaningful error message. 

System testing includes testing against non-functional requirements too. Here are some examples.

• Performance testing – to ensure the system responds quickly.
• Load testing (also called stress testing or scalability testing) – to ensure the system can work under heavy load.
• Security testing – to test how secure the system is.
• Compatibility testing, interoperability testing – to check whether the system can work with other systems.
• Usability testing – to test how easy it is to use the system.
• Portability testing – to test whether the system works on different platforms.

What

Alpha testing is performed by the users, under controlled conditions set by the software development team.

Beta testing is performed by a selected subset of target users of the system in their natural work setting.

An open beta release is the release of not-yet-production-quality-but-almost-there software to the general population. For example, Google’s Gmail was in 'beta' for many years before the label was finally removed.

What

Eating your own dog food (aka dogfooding), is a creators of a product use their own product to test the product.

What

Developer testing is the testing done by the developers themselves as opposed to professional testers or end-users.

Why

Delaying testing until the full product is complete has a number of disadvantages:

• Locating the cause of such a test case failure is difficult due to a large search space; in a large system, the search space could be millions of lines of code, written by hundreds of developers! The failure may also be due to multiple inter-related bugs.
• Fixing a bug found during such testing could result in major rework, especially if the bug originated during the design or during requirements specification (i.e. a faulty design or faulty requirements).
• One bug might 'hide' other bugs, which could emerge only after the first bug is fixed.
• The delivery may have to be delayed if too many bugs were found during testing.

Therefore, it is better to do early testing, as hinted by the popular rule of thumb given below, also illustrated by the graph below it.

The earlier a bug is found, the easier and cheaper to have it fixed.

Such early testing of partially developed software is usually, and by necessity, done by the developers themselves i.e. developer testing.

What

Here are two alternative approaches to testing a software: Scripted testing and Exploratory testing

1. Scripted testing: First write a set of test cases based on the expected behavior of the SUT, and then perform testing based on that set of test cases.

2. Exploratory testing: Devise test cases on-the-fly, creating new test cases based on the results of the past test cases.

Exploratory testing is ‘the simultaneous learning, test design, and test execution’ [source: bach-et-explained] whereby the nature of the follow-up test case is decided based on the behavior of the previous test cases. In other words, running the system and trying out various operations. It is called exploratory testing because testing is driven by observations during testing. Exploratory testing usually starts with areas identified as error-prone, based on the tester’s past experience with similar systems. One tends to conduct more tests for those operations where more faults are found.

When

Which approach is better – scripted or exploratory? A mix is better.

The success of exploratory testing depends on the tester’s prior experience and intuition. Exploratory testing should be done by experienced testers, using a clear strategy/plan/framework. Ad-hoc exploratory testing by unskilled or inexperienced testers without a clear strategy is not recommended for real-world non-trivial systems. While exploratory testing may allow us to detect some problems in a relatively short time, it is not prudent to use exploratory testing as the sole means of testing a critical system.

Scripted testing is more systematic, and hence, likely to discover more bugs given sufficient time, while exploratory testing would aid in quick error discovery, especially if the tester has a lot of experience in testing similar systems.

In some contexts, you will achieve your testing mission better through a more scripted approach; in other contexts, your mission will benefit more from the ability to create and improve tests as you execute them. I find that most situations benefit from a mix of scripted and exploratory approaches. -- [source: bach-et-explained]

What

Acceptance testing (aka User Acceptance Testing (UAT)): test the delivered system to ensure it meets the user requirements.

Acceptance tests give an assurance to the customer that the system does what it is intended to do. Acceptance test cases are often defined at the beginning of the project, usually based on the use case specification. Successful completion of UAT is often a prerequisite to the project sign-off.

Acceptance vs System Testing

Acceptance testing comes after system testing. Similar to system testing, acceptance testing involves testing the whole system.

Some differences between system testing and acceptance testing:

Note: negative test cases: cases where the SUT is not expected to work normally e.g. incorrect inputs; positive test cases: cases where the SUT is expected to work normally

Passing system tests does not necessarily mean passing acceptance testing. Some examples:

• The system might work on the testbed environments but might not work the same way in the deployment environment, due to subtle differences between the two environments.
• The system might conform to the system specification but could fail to solve the problem it was supposed to solve for the user, due to flaws in the system design.

What

When we modify a system, the modification may result in some unintended and undesirable effects on the system. Such an effect is called a regression.

Regression testing is re-testing the SUT to detect regressions. Noted that to detect regressions, we need to retest all related components, even if they were tested before.

Regression testing is more effective when it is done frequently, after each small change. However, doing so can be prohibitively expensive if testing is done manually. Hence, regression testing is more practical when it is automated.

What

Automated Testing of CLI Apps

A simple way to semi-automate testing of a CLI app is using input/output re-direction.

• First, we feed the app with a sequence of test inputs that is stored in a file while redirecting the output to another file.
  e.g., java AddressBook < input.txt > output.txt
• Next, we compare the actual output file with another file containing the expected output.
  e.g., FC output.txt expected.txt

Let us assume we are testing a CLI app called AddressBook (Example: se-edu/addressbook-level1). Here are the detailed steps:

1. Store the test input in the text file input.txt.

   add Valid Name p/12345 valid@email.butNoPrefix
   add Valid Name 12345 e/valid@email.butPhonePrefixMissing
   

2. Store the output we expect from the SUT in another text file expected.txt.

   Command: || [add Valid Name p/12345 valid@email.butNoPrefix]
   Invalid command format: add 
   
   Command: || [add Valid Name 12345 e/valid@email.butPhonePrefixMissing]
   Invalid command format: add 
   

3. Run the program as given below, which will redirect the text in input.txt as the input to AddressBook and similarly, will redirect the output of AddressBook to a text file output.txt. Note that this does not require any code changes to AddressBook.

   java AddressBook < input.txt > output.txt
   

   A CLI program takes input from the keyboard and outputs to the console. That is because those two are default input and output streams, respectively. But you can change that behavior using < and > operators. For example, if you run AddressBook in the DOS prompt, the output will be shown in the console, but if you run it like this,

   java AddressBook > output.txt 
   

   the Operating System then creates a file output.txt and stores the output in that file instead of displaying it in the console. No file I/O coding is required. Similarly, adding < input.txt (or any other filename) makes the OS redirect the contents of the file as input to the program, as if the user typed the content of the file one line at a time.

   📎 Resources:

   • Using command redirection operators in Windows

4. Next, we compare output.txt with the expected.txt. This can be done using a utility such as Windows FC (i.e. File Compare) command, Unix diff command, or a GUI tool such as Winmerge.

   FC output.txt expected.txt
   

Note that the above technique is only suitable when testing CLI apps, and only if the exact output can be predetermined. If the output varies from one run to the other (e.g. it contains a time stamp), this technique will not work. In those cases we need more sophisticated ways of automating tests.

Test Automation Using Test Drivers

A test driver is the code that ‘drives’ the SUT for the purpose of testing i.e. invoking the SUT with test inputs and verifying the behavior is as expected.

public class PayrollTestDriver {
    public static void main(String[] args) throws Exception {

        //test setup
        Payroll p = new Payroll();

        //test case 1
        p.setEmployees(new String[]{"E001", "E002"});
        // automatically verify the response
        if (p.totalSalary() != 6400) {
            throw new Error("case 1 failed ");
        }

        //test case 2
        p.setEmployees(new String[]{"E001"});
        if (p.totalSalary() != 2300) {
            throw new Error("case 2 failed ");
        }

        //more tests...

        System.out.println("All tests passed");
    }
}

Test Automation Tools

JUnit is a tool for automated testing of Java programs. Similar tools are available for other languages.

public class PayrollTestJUnit {

    @Test
    public void testTotalSalary(){
        Payroll p = new Payroll();

        //test case 1
        p.setEmployees(new String[]{"E001", "E002"});
        assertEquals(p.totalSalary(), 6400);

        //test case 2
        p.setEmployees(new String[]{"E001"});
        assertEquals(p.totalSalary(), 2300);

        //more tests...
    }
}

Most modern IDEs has integrated support for testing tools. The figure below shows the JUnit output when running some JUnit tests using the Eclipse IDE.

Automated Testing of GUIs

If a software product has a GUI component, all product-level testing (i.e. the types of testing mentioned above) need to be done using the GUI. However, testing the GUI is much harder than testing the CLI (command line interface) or API, for the following reasons:

• Most GUIs can support a large number of different operations, many of which can be performed in any arbitrary order.
• GUI operations are more difficult to automate than API testing. Reliably automating GUI operations and automatically verifying whether the GUI behaves as expected is harder than calling an operation and comparing its return value with an expected value. Therefore, automated regression testing of GUIs is rather difficult.
• The appearance of a GUI (and sometimes even behavior) can be different across platforms and even environments. For example, a GUI can behave differently based on whether it is minimized or maximized, in focus or out of focus, and in a high resolution display or a low resolution display.

One approach to overcome the challenges of testing GUIs is to minimize logic aspects in the GUI. Then, bypass the GUI to test the rest of the system using automated API testing. While this still requires the GUI to be tested manually, the number of such manual test cases can be reduced as most of the system has been tested using automated API testing.

There are testing tools that can automate GUI testing.

What

Test coverage is a metric used to measure the extent to which testing exercises the code i.e., how much of the code is 'covered' by the tests.

Here are some examples of different coverage criteria:

• Function/method coverage : based on functions executed  e.g., testing executed 90 out of 100 functions.
• Statement coverage : based on the number of line of code executed  e.g., testing executed 23k out of 25k LOC.
• Decision/branch coverage : based on the decision points exercised  e.g., an if statement evaluated to both true and false with separate test cases during testing is considered 'covered'.
• Condition coverage : based on the boolean sub-expressions, each evaluated to both true and false with different test cases. Condition coverage is not the same as the decision coverage.

• Path coverage measures coverage in terms of possible paths through a given part of the code executed. 100% path coverage means all possible paths have been executed. A commonly used notation for path analysis is called the Control Flow Graph (CFG).
• Entry/exit coverage measures coverage in terms of possible calls to and exits from the operations in the SUT.

How

Measuring coverage is often done using coverage analysis tools. Most IDEs have inbuilt support for measuring test coverage, or at least have plugins that can measure test coverage.

Coverage analysis can be useful in improving the quality of testing  e.g., if a set of test cases does not achieve 100% branch coverage, more test cases can be added to cover missed branches.

What

Dependency injection is the process of 'injecting' objects to replace current dependencies with a different object. This is often used to inject stubs to isolate the SUT from its dependencies so that it can be tested in isolation.

class Logic {
    Storage s;

    Logic(Storage s) {
        this.s = s;
    }

    String getName(int index) {
        return "Name: " + s.getName(index);
    }
}

interface Storage {
    String getName(int index);
}

class DatabaseStorage implements Storage {

    @Override
    public String getName(int index) {
        return readValueFromDatabase(index);
    }

    private String readValueFromDatabase(int index) {
        // retrieve name from the database
    }
}

Logic logic = new Logic(new DatabaseStorage());
String name = logic.getName(23);

@Test
void getName() {
    Logic logic = new Logic(new DatabaseStorage());
    assertEquals("Name: John", logic.getName(5));
}

class StorageStub implements Storage {

    @Override
    public String getName(int index) {
        if(index == 5) {
            return "Adam";
        } else {
            throw new UnsupportedOperationException();
        }
    }
}

@Test
void getName() {
    Logic logic = new Logic(new StorageStub());
    assertEquals("Name: Adam", logic.getName(5));
}

📦 A Foo object normally depends on a Bar object, but we can inject a BarStub object so that the Foo object no longer depends on a Bar object. Now we can test the Foo object in isolation from the Bar object.

How

Polymorphism can be used to implement dependency injection, as can be seen in the example given in [Quality Assurance → Testing → Unit Testing → Stubs] where a stub is injected to replace a dependency.