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.

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.

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:

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 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}

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

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

 

Paradigms → Object Oriented Programming → Inheritance →

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.

Consider the following case of EvaluationReport class inheriting the Report class:

Report methods	EvaluationReport methods	Overrides?
print()	print()	Yes
write(String)	write(String)	Yes
read():String	read(int):String	No.  Reason: the two methods have different signatures; This is a case of overloading (rather than overriding).

Paradigms → Object Oriented Programming → Inheritance →

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 case below, the calculate method is overloaded because the two methods have the same name but different type signatures (String) and (int)

• calculate(String): void
• calculate(int): void

Which of these methods override another method? A is the parent class. B inherits A.

• 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

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

In contrast, overloaded methods are resolved using static binding.

class Account {

    Account () {
        // Signature: ()
        ...
    }

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

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

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

LSP sounds same as substitutability but it goes beyond substitutability; LSP implies that a subclass should not be more restrictive than the behavior specified by the superclass. As we know, Java has language support for substitutability. However, if LSP is not followed, substituting a subclass object for a superclass object can break the functionality of the code.

 

Paradigms → Object Oriented Programming → Inheritance →

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

Suppose the Payroll class depends on the adjustMySalary(int percent) method of the Staff class. Furthermore, the Staff class states that the adjustMySalary method will work for all positive percent values. Both Admin and Academic classes override the adjustMySalary method.

Now consider the following:

• Admin#adjustMySalary method works for both negative and positive percent values.
• Academic#adjustMySalary method works for percent values 1..100 only.

In the above scenario,

• Admin class follows LSP because it fulfills Payroll’s expectation of Staff objects (i.e. it works for all positive values). Substituting Admin objects for Staff objects will not break the Payroll class functionality.
• Academic class violates LSP because it will not work for percent values over 100 as expected by the Payroll class. Substituting Academic objects for Staff objects can potentially break the Payroll class functionality.

The Rectangle#resize() can take any integers for height and width. This contract is violated by the subclass Square#resize() because it does not accept a height that is different from the width.

class Rectangle {
    ...
    /** sets the size to given height and width*/
    void resize(int height, int width){
        ...
    }
}


class Square extends Rectangle {
    
    @Override
    void resize(int height, int width){
        if (height != width) {
            //error
       }
    }
}

Now consider the following method that is written to work with the Rectangle class.

void makeSameSize(Rectangle original, Rectangle toResize){
    toResize.resize(original.getHeight(), original.getWidth());
}

This code will fail if it is called as maekSameSize(new Rectangle(12,8), new Square(4, 4)) That is, Square class is not substitutable for the Rectangle class.

More concretely, a method m of an object O should invoke only the methods of the following kinds of objects:

• The object O itself
• Objects passed as parameters of m
• Objects created/instantiated in m (directly or indirectly)
• Objects from the direct association of O

void foo(Bar b) {
    Goo g = b.getGoo();
    g.doSomething();
}

LoD aims to prevent objects navigating internal structures of other objects.

The Dependency Inversion Principle states that,

1. High-level modules should not depend on low-level modules. Both should depend on abstractions.
2. Abstractions should not depend on details. Details should depend on abstractions.

Example:

In design (a), the higher level class Payroll depends on the lower level class Employee, a violation of DIP. In design (b), both Payroll and Employee depends on the Payee interface (note that inheritance is a dependency).

Design (b) is more flexible (and less coupled) because now the Payroll class need not change when the Employee class changes.

The five OOP principles given below are known as SOLID Principles (an acronym made up of the first letter of each principle):

Supplmentary → Principles →

Open-Closed Principle

The Open-Close Principle aims to make a code entity easy to adapt and reuse without needing to modify the code entity itself.

Open-Closed Principle (OCP): A module should be open for extension but closed for modification. That is, modules should be written so that they can be extended, without requiring them to be modified. _{-- proposed by Bertrand Meyer}

In object-oriented programming, OCP can be achieved in various ways. This often requires separating the specification (i.e. interface) of a module from its implementation.

In the design given below, the behavior of the CommandQueue class can be altered by adding more concrete Command subclasses. For example, by including a Delete class alongside List, Sort, and Reset, the CommandQueue can now perform delete commands without modifying its code at all. That is, its behavior was extended without having to modify its code. Hence, it was open to extensions, but closed to modification.

The behavior of a Java generic class can be altered by passing it a different class as a parameter. In the code below, the ArrayList class behaves as a container of Students in one instance and as a container of Admin objects in the other instance, without having to change its code. That is, the behavior of the ArrayList class is extended without modifying its code.

ArrayList students = new ArrayList< Student >();
ArrayList admins = new ArrayList< Admin >();  	

Which of these is closest to the meaning of the open-closed principle?

• a. We should be able to change a software module’s behavior without modifying its code.
• b. A software module should remain open to modification as long as possible.
• c. A software module should be open to modification and closed to extension.
• d. Open source software rocks. Closed source software sucks.

(a)

Explanation: Please refer the handout for the definition of OCP.

Supplmentary → Principles →

Liskov Substitution Principle

Liskov Substitution Principle (LSP): Derived classes must be substitutable for their base classes. _{-- proposed by Barbara Liskov}

LSP sounds same as substitutability but it goes beyond substitutability; LSP implies that a subclass should not be more restrictive than the behavior specified by the superclass. As we know, Java has language support for substitutability. However, if LSP is not followed, substituting a subclass object for a superclass object can break the functionality of the code.

 

Paradigms → Object Oriented Programming → Inheritance →

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

Suppose the Payroll class depends on the adjustMySalary(int percent) method of the Staff class. Furthermore, the Staff class states that the adjustMySalary method will work for all positive percent values. Both Admin and Academic classes override the adjustMySalary method.

Now consider the following:

• Admin#adjustMySalary method works for both negative and positive percent values.
• Academic#adjustMySalary method works for percent values 1..100 only.

In the above scenario,

• Admin class follows LSP because it fulfills Payroll’s expectation of Staff objects (i.e. it works for all positive values). Substituting Admin objects for Staff objects will not break the Payroll class functionality.
• Academic class violates LSP because it will not work for percent values over 100 as expected by the Payroll class. Substituting Academic objects for Staff objects can potentially break the Payroll class functionality.

The Rectangle#resize() can take any integers for height and width. This contract is violated by the subclass Square#resize() because it does not accept a height that is different from the width.

class Rectangle {
    ...
    /** sets the size to given height and width*/
    void resize(int height, int width){
        ...
    }
}


class Square extends Rectangle {
    
    @Override
    void resize(int height, int width){
        if (height != width) {
            //error
       }
    }
}

Now consider the following method that is written to work with the Rectangle class.

void makeSameSize(Rectangle original, Rectangle toResize){
    toResize.resize(original.getHeight(), original.getWidth());
}

This code will fail if it is called as maekSameSize(new Rectangle(12,8), new Square(4, 4)) That is, Square class is not substitutable for the Rectangle class.

If a subclass imposes more restrictive conditions than its parent class, it violates Liskov Substitution Principle.

• True
• False

True.

Explanation: If the subclass is more restrictive than the parent class, code that worked with the parent class may not work with the child class. Hence, the substitutability does not exist and LSP has been violated.

Supplmentary → Principles →

Interface Segregation Principle

Interface Segregation Principle (ISP): No client should be forced to depend on methods it does not use.

The Payroll class should not depend on the AdminStaff class because it does not use the arrangeMeeting() method. Instead, it should depend on the SalariedStaff interface.

public class Payroll {
    //...    
    private void adjustSalaries(AdminStaff adminStaff){ //violates ISP
        //...
    }

}

public class Payroll {
    //...    
    private void adjustSalaries(SalariedStaff staff){ //does not violate ISP
        //...
    }
}

Supplmentary → Principles →

Dependency Inversion Principle

The Dependency Inversion Principle states that,

1. High-level modules should not depend on low-level modules. Both should depend on abstractions.
2. Abstractions should not depend on details. Details should depend on abstractions.

Example:

In design (a), the higher level class Payroll depends on the lower level class Employee, a violation of DIP. In design (b), both Payroll and Employee depends on the Payee interface (note that inheritance is a dependency).

Design (b) is more flexible (and less coupled) because now the Payroll class need not change when the Employee class changes.

Which of these statements is true about the Dependency Inversion Principle.

• a. It can complicate the design/implementation by introducing extra abstractions, but it has some benefits.
• b. It is often used during testing, to replace dependencies with mocks.
• c. It reduces dependencies in a design.
• d. It advocates making higher level classes to depend on lower level classes.

• a. It can complicate the design/implementation by introducing extra abstractions, but it has some benefits.
• b. It is often used during testing, to replace dependencies with mocks.
• c. It reduces dependencies in a design.
• d. It advocates making higher level classes to depend on lower level classes.

Explanation: Replacing dependencies with mocks is Dependency Injection, not DIP. DIP does not reduce dependencies, rather, it changes the direction of dependencies. Yes, it can introduce extra abstractions but often the benefit can outweigh the extra complications.

The principle says that some capability we presume our software needs in the future should not be built now because the chances are "you aren't gonna need it". The rationale is that we do not have perfect information about the future and therefore some of the extra work we do to fulfill a potential future need might go to waste when some of our predictions fail to materialize.

This principle guards against duplication of information.

Explanation: The additional communication overhead will outweigh the benefit of adding extra manpower, especially if done near to a deadline.

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.

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
    }

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;
    }
    …
}

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.

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.

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

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.

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

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.