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.

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.

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

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:

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.

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.

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

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.

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)

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.

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

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.

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

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.

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

📦 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) { ... }
}

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

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

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

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

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.

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.

Use Case Diagrams

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

📦 A simple use case diagram:

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

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.

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

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

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

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.

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

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

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

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

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

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

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

Except for trivial SUTs, exhaustive testing is not practical because such testing often requires a massive/infinite number of test cases.

Program testing can be used to show the presence of bugs, but never to show their absence!
_{--Edsger Dijkstra}

Black Box vs Glass Box

Test case design can be of three types, based on how much of SUT internal details are considered when designing test cases:

• Black-box (aka specification-based or responsibility-based) approach: test cases are designed exclusively based on the SUT’s specified external behavior.

• White-box (aka glass-box or structured or implementation-based) approach: test cases are designed based on what is known about the SUT’s implementation, i.e. the code.

• Gray-box approach: test case design uses some important information about the implementation. For example, if the implementation of a sort operation uses different algorithms to sort lists shorter than 1000 items and lists longer than 1000 items, more meaningful test cases can then be added to verify the correctness of both algorithms.

What

Consider the testing of the following operation.

It is inefficient and impractical to test this method for all integer values [-MIN_INT to MAX_INT]. Fortunately, there is no need to test all possible input values. For example, if the input value 233 failed to produce the correct result, the input 234 is likely to fail too; there is no need to test both.

In general, most SUTs do not treat each input in a unique way. Instead, they process all possible inputs in a small number of distinct ways. That means a range of inputs is treated the same way inside the SUT. Equivalence partitioning (EP) is a test case design technique that uses the above observation to improve the E&E of testing.

By dividing possible inputs into equivalence partitions we can,

• avoid testing too many inputs from one partition. Testing too many inputs from the same partition is unlikely to find new bugs. This increases the efficiency of testing by reducing redundant test cases.
• ensure all partitions are tested. Missing partitions can result in bugs going unnoticed. This increases the effectiveness of testing by increasing the chance of finding bugs.

Basic

Equivalence partitions (EPs) are usually derived from the specifications of the SUT.

When the SUT has multiple inputs, you should identify EPs for each input.

An EP may not have adjacent values.

Some inputs have only a small number of possible values and a potentially unique behavior for each value. In those cases we have to consider each value as a partition by itself.

Note that the EP technique is merely a heuristic and not an exact science, especially when applied manually (as opposed to using an automated program analysis tool to derive EPs). The partitions derived depend on how one ‘speculates’ the SUT to behave internally. Applying EP under a glass-box or gray-box approach can yield more precise partitions.

Intermediate

When deciding EPs of OOP methods, we need to identify EPs of all data participants that can potentially influence the behaviour of the method, such as,

• the target object of the method call
• input parameters of the method call
• other data/objects accessed by the method such as global variables. This category may not be applicable if using the black box approach (because the test case designer using the black box approach will not know how the method is implemented)

/**
 * Adds o to the top of the stack if the stack is not full.
 * @throws MutabilityException if the global flag FREEZE==true.
 * @throws InvalidValueException if  o is null.
 * @return true if the push operation was a success.
 */
boolean push(Object o) {
    ...
}

What

Boundary Value Analysis (BVA) is test case design heuristic that is based on the observation that bugs often result from incorrect handling of boundaries of equivalence partitions. This is not surprising, as the end points of the boundary are often used in branching instructions etc. where the programmer can make mistakes.

BVA suggests that when picking test inputs from an equivalence partition, values near boundaries (i.e. boundary values) are more likely to find bugs.

Boundary values are sometimes called corner cases.

How

Typically, we choose three values around the boundary to test: one value from the boundary, one value just below the boundary, and one value just above the boundary. The number of values to pick depends on other factors, such as the cost of each test case.

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

Revision Control Software (RCS) are the software tools that automate the process of Revision Control i.e. managing revisions of software artifacts.

Revision control is also known as Version Control Software (VCS), and a few other names. Here, we use the terms revision and version interchangeably.

What

UML class diagrams describe the structure (but not the behavior) of an OOP solution. These are possibly the most often used diagrams in the industry and an indispensable tool for an OO programmer.

📦 An example class diagram:

What

The basic UML notations used to represent a class:

📦 A Table class shown in UML notation:

class Table{
    
    Integer number;
    Chair[] chairs = null;
    
    Integer getNumber(){
        ...
    }
    
    void setNumber(Integer n){
        ...
    }
}

The 'Operations' compartment and/or the 'Attributes' compartment may be omitted if such details are not important for the task at hand. 'Attributes' always appear above the 'Operations' compartment. All operations should be in one compartment rather than each operation in a separate compartment. Same goes for attributes.

The visibility of attributes and operations is used to indicate the level of access allowed for each attribute or operation. The types of visibility and their exact meanings depend on the programming language used. Here are some common visibilities and how they are indicated in a class diagram:

• + : public
• - : private
• # : protected
• ~ : package private

📦 Table class with visibilities shown:

Basic

We use a solid line to show an association between two classes.

Navigability

We use arrow heads to indication the navigability of an association.

📦 Logic is aware of Minefield, but Minefield is not aware of Logic

class Logic{
    Minefield minefield;
}

class Minefield{
    ...
}

Navigability can be shown in class diagrams as well as object diagrams.

Roles

Association Role labels are used to indicate the role played by the classes in the association.

📦 This association represents a marriage between a Man object and a Woman object. The respective roles played by objects of these two classes are husband and wife.

Note how the variable names match closely with the association roles.

class Man{
    Woman wife;
}

class Woman{
    Man husband;
}

📦 The role of Student objects in this association is charges (i.e. Admin is in charge of students)

class Admin{
    List<Student> charges;
}

Labels

Association labels describe the meaning of the association. The arrow head indicates the direction in which the label is to be read.

📦 In this example, the same association is described using two different labels.

• Diagram on the left: Admin class is associated with Student class because an Admin object uses a Student object.
• Diagram on the right: Admin class is associated with Student class because a Student object is used by an Admin object.

Multiplicity

Commonly used multiplicities:

• 0..1 : optional, can be linked to 0 or 1 objects
• 1 : compulsory, must be linked to one object at all times.
• * : can be linked to 0 or more objects.
• n..m : the number of linked objects must be n to m inclusive

📦 In the diagram below, an Admin object administers (in charge of) any number of students but a Student object must always be under the charge of exactly one Admin object

📦 In the diagram below,

• Each student must be supervised by exactly one professor. i.e. There cannot be a student who doesn't have a supervisor or has multiple supervisors.
• A professor cannot supervise more than 5 students but can have no students to supervise.
• An admin can handle any number of professors and any number of students, including none.
• A professor/student can be handled by any number of admins, including none.

Associations as Attributes

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

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

name: type [multiplicity] = default value

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

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

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

Class-Level Members

In UML class diagrams, underlines denote class-level attributes and variables.

📦 In the class below, totalStudents attribute and the getTotalStudents method are class-level.

Composition

UML uses a solid diamond symbol to denote composition.

Notation:

📦 A Book consists of Chapter objects. When the Book object is destroyed, its Chapter objects are destroyed too.

Aggregation

UML uses a hollow diamond is used to indicate an aggregation.

📦 Example:

Inheritance

You can use a triangle and a solid line (not to be confused with an arrow) to indicate class inheritance.

Notation:

📦 Examples: The Car class inherits from the Vehicle class. The Cat and Dog classes inherit from the Pet class.

Introduction

An object diagram shows an object structure at a given point of time.

Objects

Notation:

Notes:

• The class name and object name e.g. car1:Car are underlined.
• objectName:ClassName is meant to say 'an instance of ClassName identified as objectName'.
• Unlike classes, there is no compartment for methods.
• Attributes compartment can be omitted if it is not relevant to the task at hand.
• Object name can be omitted too e.g. :Car which is meant to say 'an unnamed instance of a Car object'.

📦 Some example objects:

What

A solid line indicates an association between two objects.

Introduction

A UML Activity diagram (AD) can model workflows.

Linear Paths

An activity diagram (AD) captures an activity of actions and control flows that makes up the activity.

• An action is a single step in an activity. It is shown as a rectangle with rounded corners.
• A control flow shows the flow of control from one action to the next. It is shown by drawing a line with an arrow-head to show the direction of the flow.

Note the slight difference between the start node and the end node which represent the start and the end of the activity, respectively.

📦 This activity diagram shows the action sequence of the activity a passenger rides the bus:

Alternate Paths

A branch node shows the start of alternate paths. Each control flow exiting a branch node has a guard condition : a boolean condition that should be true for execution to take that path. Only one of the guard condition can be true at any time.

A merge node shows the end of alternate paths.

Both branch nodes and merge nodes are diamond shapes. Guard conditions must be in square brackets.

📦 The AD below shows alternate paths involved in the workflow of the activity shop for product:

Parallel Paths

Fork nodes indicate the start of concurrent flows of control.

Join nodes indicate the end of parallel paths.

Both have the same notation: a bar.

In a set of parallel paths, execution along all parallel paths should be complete before the execution can start on the outgoing control flow of the join.

📦 In this activity diagram (from an online shop website) the actions User browsers products and System records browsing data happen in parallel. Both of them need to finish before the log out action can take place.

Notes

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

📦 Example: