Software Requirements - Part 2

This is the second part of the following book summary.

Previous posts:

• Software Requirements - Part 1

Let's continue our discussion with new questions.

Who is a customer?

An individual or organization who derives either direct or indirect benefit from a product.

It is clear that customer development relationship is extremely critical to software project success.

Who is a user?

What? Is not the same as the customer? Well, not necessary!

So, what is the difference between Users and Customers?

Users use your product. Customers buy it.

Your users may be the customers and this is often the case for commercial software development. However, it is important to remember that this is not always true.

Who are the stakeholders?

From Wikipedia:

Stakeholders are anyone who has an interest in the project. Project stakeholders are individuals and organizations that are actively involved in the project, or whose interests may be affected as a result of project execution or project completion.

All stakeholders share a common objective:

Build a successful software product that provides adequate business value and rewards to all stakeholders

Excellent software products are the result of a well-executed design based on excellent requirements. High-quality requirements result from effective communication and collaboration between developers and customers - a partnership.

A collaborative effort can work only when all parties involved know what they need to be successful and when they understand and respect what their collaborators need to be successful.

What are the rights of software customers?

1. Expect analysts to speak your language
2. Expect analysts to learn about your business and your objectives for the system
3. Expect analysts to structure the information you present during requirements elicitation into a written software requirements specification
4. Have analysts explain all work products created from the requirements process
5. Expect analysts and developers to treat you with respect and to maintain a collaborative and professional attitude throughout your interactions
6. Have analysts and developers provide ideas and alternatives both for your requirements and for implementation of the product
7. Describe characteristics of the product that will make it easy and enjoyable to use.
8. Be given opportunity to adjust your requirements to permit reuse of existing software components
9. Receive good-faith estimates of the costs, impacts, and trade-offs when you request a change in the requirements
10. Receive a system that meets your functional and quality needs, to the extent that those needs have been communicated to the developers and agreed upon

What are the duties of software customers?

1. Educate analysts and developers about your business and define business jargon. The intent is not to transform analysts into domain expert, but to help them understand your problems and objectives.
2. Spend the time that it takes to provide requirements, clarify them, and iteratively flesh them out
3. Be specific and precise when providing input about the system's requirements.
4. Make timely decisions about requirements when requested to do so
5. Respect a developer's assessment of the cost and feasibility of requirements
6. In collaboration with the developers, set priorities for functional requirements, system features, or use cases.
7. Review requirements documents and evaluate prototypes.
8. Communicate changes to the requirements as soon as you know about them.
9. Follow the development organization's process for requesting requirements changes.
10. Respect the processes the analysts use for requirements engineering.

What is the concept of Signing Off on the requirements document?

Many organizations use it as the make of customer approval of those requirements. 

The sign means:

I agree that this document represents our best understanding of the requirements for this project today and that the system described will satisfy our needs. I agree to make future changes in this baseline through he project's defined change process. I realize that approved changes might require us to renegotiate the cost, resource, and schedule commitments for this project.

This definition is extremely important because it contains an important thing. Everyone agree that it's impossible to know all the requirements early in the project and that requirements will undoubtedly change over time. This is why the signing process should never used as a weapon.

The most important thing of the sign-off ritual is the concept of establishing a Baseline of the requirements agreement, a snapshot of it at a point in time.

What software development methodology to use?

The author of the book explicitly say that being a strong supporter of a specific software development methodology is not usually desirable.  It is by far, more important to identify and apply industry best practices rather than devising or purchasing a whole-cloth solution.

Even if you do adopt a commercial methodology, adapt it to best suit your needs and augment its components with other effective practices from your tool-kit.

I don't have a strong experience but I have to say that I entirely agree with him. This seems the most pragmatic way to approach the problem.

So, what are good practices for Requirements Engineering?

Some generic practices are:

• Train requirements analysts
• Educate user representatives and managers about requirements
• Train developers in application domain concepts
• Create a project glossary
• Document the steps your organization follows to elicit, analyse, specify and validate requirements.

Let me remember the typical steps of requirements engineering:

• Requirements Development
• Requirements Elicitation
• Requirements Analysis
• Requirements Specification
• Requirements Validation
• Requirements Management

Let's see what are the good practices for each type of requirements engineering.

What are good practices for Requirements Elicitation?

• Write a vision and scope document
• Identify user classes and their characteristics
• Select a product champion for each user class
• Establish focus groups of typical users
• Work with user representatives to identify use cases
• Identify system events and responses
• Hold facilitated elicitation workshops
• Observe users performing their jobs

What are good practices for Requirements Analysis?

• Draw a context diagram
• Create user interfaces and technical prototypes
• Analyse requirement feasibility
• Prioritize the requirements
• Model the requirements
• Create a data dictionary
• Allocate requirements to subsystems
• Apply quality function deployment

What are good practices for Requirements Specification?

• Adopt an SRS template
• Identify sources of requirements
• Uniquely label each requirement
• Record business rules
• Specify quality attributes

Remember that the goal is to develop requirements of sufficient quality and detail that managers can construct realistic project estimates and technical staff can proceed with design, construction, and testing.

What are good practices for Requirements Validation?

• Inspect requirements documents
• Test the requirements
• Define acceptance criteria

What are good practices for Requirements Management?

• Define a requirements change-control process
• Establish a Change Control Board (CCB)
• Perform requirements-change impact analysis
• Establish a baseline and control versions of requirements documents
• Maintain a history of requirements changes
• Track the status of each requirement
• Measure requirements volatility
• Use a requirements management tool
• Create a requirements traceability matrix

What are good practices for Project Management?

• Select an appropriate software development life cycle
• Base project plans on requirements
• Renegotiate project commitments when requirements change
• Document and manage requirements related risks
• Track the effort spent on requirements engineering
• Review lessons learnt regarding requirements on other projects (project retrospectives)

Should I adopt all the practices?

Please, No!

As I already said, you should think of these good practices as new items for your requirements tool-kit. Consider your business and processes and choose the practices that can provide you the most benefits.

You should never forget the 80-20 rule and that the most important thing is to have a continual improvement process.

The website associated with the book contains a lot of templates that can be used as a starting point. Unfortunately, you need to pay for them.

I would like to finish this post with a sentence with effect:

Gathering and validating requirements are among the greatest challenges is software development

Next post:

• Software Requirements - Part 3

Software Requirements - Part 1

In the 1995 the Standish Group did a very revealing research called The Chaos Report.

The research shows a staggering 31.1% of projects will be cancelled before they ever get completed. Further results indicate 52.7% of projects will cost 189% of their original estimates.

Lack of user input and incomplete requirements and specifications were listed as the main causes of project failures. Errors made during the requirements stage account for 40 to 60 % of all defects found in a software project (Davis 1993; Leffingwell 1997)

In the last two decades new methodologies has been created and adopted but these are still fundamental problems in software companies. This is why I decided to study more about the subject.

After an attentive analysis I decided to read the following book:


In this post, and subsequent posts I would like to summarise the book and describe what I found most interesting.

One thing that I like about the book is that it is completely independent by a specific methodology. This allows me to create a big picture of the topic before digging into specifics.

Everything start from a question.

What is a software requirement?

There is no universal definition of what a requirement is.

There is a formal definition from IEEE but in few words we can say that:

Requirements are descriptions of how a system should behave or of a system property or attribute. Requirements may also be a constraint on the development process of the system.

The absence of a unique definition means that you shouldn't assume that all your project stakeholders share a common notion of what requirements are and that it is good to define your specific definition.

Are there multiple types of requirements?

Yes and it is very important to understand the differences between them:

• Business Requirements
• High-Level objective
• Explain why the organisation is implementing the system.
• Usually stored in a "Vision and scope" document
• User Requirements
• User goals or tasks that the users must be able to perform with the product
• Must align with the business requirements
• Functional Requirements
• Software functionality that the developers must build into the product to enable users to accomplish their tasks, thereby satisfying the business requirements
• System Requirements
• Top level requirements for a product that contains multiple subsystems
• Non functional Requirements
• Usability, portability, integrity, efficiency, robustness, ...
• Also called: Quality Attributes

In addition, there are other important terms that are frequently used in the context of software requirements:

• Business Rules
• Corporate policies, government regulations, industry standards, ...
• There are usually requirements associated to business rules
• Feature
• A set of logically related functional requirements that provides a capability to the user and enables the satisfaction of a business objective
• Software Requirements Specification (SRS) 
• Describes as fully as necessary the expected behaviour of the software system. Do not include design or implementation details, project planning or testing info.

What do you mean by Requirements Engineering?

From Wikipedia:

Requirements engineering (RE) is a systems and software engineering process which covers all of the activities involved in discovering, documenting and maintaining a set of requirements for a computer-based system

It is possible to distinguish between two types of Requirements Engineering:

• Requirements Development
• Elicitation
• Identifying the product's expected user classes
• Eliciting need from individuals who represent each user class
• Understanding user tasks and goals and the business objectives with which those tasks align
• Analysis
• Analysing the information received from users to distinguish their task goals from functional requirements, non functional requirements, business rules, suggested solutions, and extraneous information
• Understanding the relative importance of quality attributes
• Negotiating implementation priorities
• Specification
• Allocating portions of the top-level requirements to software components defined in the system architecture
• Translating the collected user needs into written requirements specifications and models
• Validation
• Reviewing the documented requirements to ensure a common understanding of the users' stated requirements and to correct any problems before the development group accepts them
• Requirements Management
• Establishing and maintaining an agreement with the customer on the requirements for the software project
• Defining the requirements baseline (snapshot in time representing the currently agreed-upon body of requirements for a specific release)
• Reviewing proposed requirements changes and evaluating the likely impact of each change before approving it
• Incorporating approved requirements changes into the project in a controlled way
• Keeping project plans current with the requirements
• Negotiating new commitments based on the estimated impact of requirements changes
• Tracing individual requirements to their corresponding designs
• Tracking requirements status and change activity throughout the project

The boundary between the two requirements processes can be described by the following image:

It is interesting to show the graph about the relative cost to correct a requirement defect depending on when it is discovered.

What are the benefits from a High-Quality Requirements Process?

• Better understanding of the user community or market
• Generates enthusiasm for the product and builds customer loyalty
• Fewer requirements defects
• Reducing development rework during the late development stages and throughout the lengthy maintenance period
• Fewer unnecessary features
• Lower enhancement costs
• Faster development
• Fewer miscommunications
• Reduced scope creep
• Reduced project chaos
• More accurate system-testing estimates
• Higher customer and team member satisfaction

Let me finish this post with some theoretical but extremely important information.

What are the characteristics of Excellent Requirements?

• Complete
• Must fully describe the functionality to be delivered
• Must contain all the information necessary for the developer to design and implement that bit of functionality
• Correct
• Must accurately describe the functionality to be built.
• Feasible
• It must be possible to implement each requirement within the known capabilities and limitations of the system and its operating environment.
• Incremental development approaches and proof-of-concept prototypes are ways to evaluate requirement feasibility
• Necessary
• Should document a capability that the customers really need or one that's required for conformance to an external system requirement or standard
• Prioritised
• Unambiguous
• Verifiable

The entire set of requirements must be:

• Complete
• No requirements should be absent.
• Consistent
• No conflicts with other requirements
• Modifiable
• Maintain history of changes made to each requirement
• Traceable
• Can be linked backward to its origin and forward to the design elements and source code that implement it and to the test cases
• Each requirement must be uniquely labelled and appear only once

This list of characteristics is obviously desirable but almost never fully achievable in practise. 

The best way to tell whether your requirements have these desired attributes is to have several project stakeholders carefully review the software requirements specification document.

Next post:

• Software Requirements - Part 2

Top Coder Problem - Boxing

TopCoder is an amazing platform to challenge yourself.

I decided to start posting my solutions to problems with the following purposes:

• Stimulate myself to practice more
• Stimulate my friends to solve the problem
• Stimulate my friends to join TopCoder and challenge themselves
• Compare and contrast different solutions

Notes:

• TopCoder only accepts solution written in C# 2.0
• The problem statement is the exclusive and proprietary property of TopCoder. You need to login to see it.

TopCoder Problem:
Boxing

This problem was used for:
2004 TCO Online Round 3 - Division I, Level One


My solution:

Tests:

My solution is an usage example of the Greedy Algorithm Design Paradigm.

What is your solution?

The Facade Pattern in .NET

The Facade Pattern provides a unified interface to a set of interfaces in a subsystem. Facade defines a higher level interface that makes the subsystem easier to use.

The Facade Pattern is the simplest of the patterns and it is something that many developers probably used a lot in the past without even knowing that there was a name for it. 

It is all about creating a class that simplifies and unifies a set of more complex classes that belong to some subsystem. However a Facade typically does not hide the complex subsystem but simply provide a different simplified view of it. This means that is always possible to use the complex subsystem when needed and that is theoretically possible to have multiple Facades per subsystem.

This pattern typically use the technique of "wrapping" to accomplish the goal. It is important however to remember that the intent of the pattern is to reduce complexity and not to adapt different interfaces like the Adapter Pattern.

I think that it is not worth creating an artificial example to showcase the Facade Pattern. It is more valuable to show examples of usage in the .NET Framework.

A primitive way to implement a Facade is using a static class.

The most significant example in .NET is surely the class File that provide a simple way to interact with the file system in a very intuitive way instead of using lower level abstractions like streams.

This method hides a lot of complexity. If you look inside the .NET Framework source code you find something similar to this:

An another example of Facade in the framework is the class WebClient that allows to easily download a web page from a server without dealing with the HTTP protocol and the sockets.

The beauty of the pattern is then in its simplicity and obviousness.

In addition of simplifying the access to a subsystem the pattern allows to decouple your client implementation from the subsystem. If future version of the subsystem changes the internal components this will not require to update the client code assuming that the Facade API remains unchanged.

Scope of Local Variables in C# and C++

Consider the following code in C++:

This code actually compile and the output is the following:

The important thing to notice here is that in C++ is possible to declare a variable with the same name in a nested block.

In fact the standard documentation say:

"A name declared in a block is local to that block; it has block scope. Its potential scope begins at its point of declaration and ends at the end of its block. A variable declared at block scope is a local variable."

In C# this is not possible. The following code does not compile:

In C# you cannot declare another local variable with the same name in the current block or in any nested blocks. In addition, the variable scope extends in both directions throughout its code block. 

Even the following code does not compile:

I would say that the restriction imposed by C# is good and avoid unexpected behaviours in some situations. It also encourages to use meaningful names for variables avoiding to reuse the same variable for different purposes.

However, the following C# code compiles:

This because the two blocks are not related to each others. They are not part of the same chain of nested blocks. This is good because there is a typical situation when you like to reuse the same variable name in loops. 

This code compiles:

The Adapter Pattern in .NET

The Adapter Pattern converts the interface of a class into another interface the clients expect. Adapter lets classes work together that couldn't otherwise because of incompatible interfaces.

The pattern is also called "Wrapper" because it is usually implemented using the technique of wrapping objects (object composition).

There are different situation when the pattern can be useful but a typical scenario is when you create an abstraction above code that is likely to change in the future. In this way, instead of changing the client code in the future the only thing to do will be implementing a particular adapter.

Let's see immediately an example.

Instead of defining an abstraction myself, I decided to base my example on the  DbDataAdapter class available in the .NET Framework that defines an abstraction for data access operations. 

Suppose we have a simple application that print the list of all the customers extracted from a local SQL server database.

This is an example of execution:

Suppose that a new vendor release a special file based database with the following code.

Assume the following new requirement:

• Use the new file database instead of SQL Server

It is obvious that the FileDb interface is completely different and incompatible with the interface expected by the client application.

What do you do?

You can use the Adapter Pattern!

In particular, you can create a specific DbDataAdapter class.

Of course you need to migrate the data from SQL Server to the file database:

The beauty of the pattern is that you don't need to change the client code. The only thing that you need to do is to simply use the new FileDbDataAdapter.

All the changes to implement the requirement are encapsulated in a single class: FileDbDataAdapter. 

The designer of the application created the adapter abstraction since the beginning because he was aware that changes of the data access code are highly likely in the future. If this abstraction was not created the change would have been more intrusive that this.

Most of the applications using third party libraries use adapters as a middle layer between the application and the library itself to decouple the application from the library. If another library has to be used only an adapter for the new library is required without having to change the application code.

The main Object Oriented Principles used by the Adapter Pattern are the following:

• Favor composition over inheritance
• Encapsulate what varies
• Program to interfaces, not implementation
• Open/Closed principle

The Command Pattern in .NET

The Command Pattern encapsulates a request as an object, thereby letting you parameterize other objects with different requests, queue or log requests, and support undoable operations.

The formal definition of the pattern is quite general and it shows how the pattern is versatile and can be used in many scenarios but the real important thing however is the first sentence, the idea that you can define a command in order to encapsulate a request to do something and use that command as a normal object. 

The Command Pattern allows you to encapsulate a method invocation.

The biggest benefit is separating the object making requests from the objects that receive and execute the requests. 

In order to describe the pattern I will implement a very simple transactional installer.

Let's assume we have the following requirements:

1. The installer allows you to execute an operation
2. The installer is independent by the specific operation executed
3. The installer is able to roll back an operation in case of errors
4. The installer is able to execute multiple operations as a transaction that is if something goes wrong all previously executed operations will be rolled back

The Command Pattern is the best way to solve this problem.

Let's start to define the command abstraction:

We can easily satisfy the first three requirements defining an installer that accept an instance of the command and calls its methods when requested.

As you can see, the Installer class is completely independent by the specific command that is provided in its constructor. In the same way, the command itself is also completely independent by the Installer.

You can define as many commands as you want:

You can easily create a program to execute some operations:

Super easy isn't it?

What about supporting transactions?

It is here that the real beauty of the pattern comes  in. Because you treat a  command as a normal object, you can aggregate them. Nobody stops you to define a kind of Meta Command that aggregate lots of commands together and in addition implement the support for transactions.

Consider that the TransactionInstallerCommand is still a command. This means that you can use the Installer class without any changes to run a set of commands in a transactional way.

Let's see an example of usage.

Is it not amazing?

In order to simulate an error I created a special command that throws an exception all the time is called.

This is the output of the program:

This example and the Command Pattern is a demonstration of many Object Oriented Principles

Encapsulate what varies

The implementation and the number of each operation is what varies and we encapsulated this creating the CommandInstaller abstraction.

Favor composition over inheritance

The Installer use a Command using composition. The same does the transaction command that compose many commands together in order to create an extremely flexible command.

Program to interfaces not implementations

Depend on abstractions. Don't depend on concrete classes

Strive for loosely coupled designs between objects that interact

InstallerCommand is the main interface introduced here that allows a very loosely coupled design with the Installer.

Classes should be open for extension but closed for modifications

It is very easy to create a new command and you don't need to change the TransactionInstallerCommand in order to use it. TransactionInstallerCommand satisfy the Open/Closed principle.

We didn't finish yet because I am sure you have a question.

In .NET we have delegates and lambda as a way to represent code as an object. At the end of the day, this is what the command pattern is about or not?

This is absolutely true!

.NET developers are now quite familiar with code like this:

If you think carefully the Where method is accepting a command as an input and it is independent by the specific command provided. In this case the command is a predicate that is a function that takes an argument and returns a boolean as the result.

In addition, the predicate requested is just a specific instance of the generic delegate called Func defined as follow:

This Func object is actually the declaration of a generic command.

How would you implement a method similar to Where without having delegates?

Using the Command Pattern of course!

Let's try to do this.

This is an example of usage:

What is wrong about this?

Nothing! However you can easily agree with me that the solution using lambda has a big advantage: you don't need to create a new class all the times you need a new command. 

LINQ has been introduced in the language starting from the version 3.0 of C# and is the biggest implementation in the entire framework of the command pattern using lambdas.

LINQ together with some new features made the C# a better language enabling  some of the most useful features available in so called functional languages. 

Three years since my Master Degree in Computer Science Engineering

Tomorrow will be three years since my Master Degree in Computer Science Engineering.

I got my degree from the University of Pisa and I am writing this post to simply remember that unforgettable day.

The title of my degree thesis (translated in English) was "Modular architecture for testing smartcard-based solutions" and here you can find the original paper:

http://retis.sssup.it/~tommaso/TesiAngellaAndrea.pdf

The following is a video of my formal presentation (obviously in Italian). I still can't believe how relaxed I was that day and how good the presentation was. Fortunately, being a speaker in DotNetToscana helped me a lot for that event.

It is impossible to forget the satisfaction of getting the maximum score: 110/110 with Honours and the unique certification of excellence. I order to get the certificate of excellence I had to do 5 additional exams with strict deadlines: Computer Science applied to biological systems, Dynamic Systems, Web Algorithms, Game Theory and Computational Intelligence. That was hard but extremely rewarding.

You can find the complete photo album here: Master Degree and Party.

Let me show few pictures from the project itself.

The SCOTT Architecture (Smart Card Open Test Toolkit):

An example of interaction with the SCOTT Shell:

The project was written in C++ with the ability to run on Windows and Linux.

I tested it with the Cryptoflex 8K Card and the TODOS Argos Mini Card Reader:

The following are the class diagrams of the simple and complex types. I had to define a type system and write the relative parser in the SCOTT shell (lots of fun!).

I like the macro I used to define a type naming convention for smart pointers and more complex data structures like maps and vectors of smart pointers. Unfortunately C++ is not like C# and I found this solution a good compromise to think like having List and Dictionary and almost forget about memory management.

The following code defines a smart pointer to vector/map of smart pointers to SValue:

This was also the first project where I started to use Unit Testing and understand the importance:

The entire project is almost 10000 lines of source code and I released it as open source but it is abandoned. If you are curious you can download the source code from the official repository.

The Singleton Pattern in .NET - If you can avoid it

NOTE: This pattern is now considered by many (included the creators) an anti pattern and it is presented only for completeness! Read why.

The Singleton Pattern ensures a class has only one instance, and provides a global point of access to it.

A Singleton is a class that manages a single instance of itself and prevent any other class from creating a new instance on its own. The only way to get the instance is passing through the Singleton class itself. 

Singletons are frequently used to provide a global access point for some service.

Let's see an example of Singleton that implement a trivial logging service.

and an example of usage:

OK but... what are the advantages?

As we said in the definition of the pattern, the main advantages are:

• Making sure that there is a single instance of the service. This is accomplished making the constructor private and the class sealed.
• Providing a global point of access to that instance.

Mmm but I can solve the same problem writing the following code, right?

It is true!

However, there are still some advantages in using the Singleton approach:

• You don't have to put the static keyword everywhere
• You can use singletons as parameters or objects
• You can implement singleton with interfaces
• You can write tests even if this is not simple

Anyway, singletons have more problems than benefits and these days many developers tend to avoid it if they can.

The biggest problem is the fact that you can use singletons where you want (they are like global variables) and dependencies are hidden inside the client objects. This means that the interface of the client objects don't reveals all the dependencies and this make testing very hard. In addition, in order to be able to write the tests you have to create a mechanism to replace singletons with mocks (a static Initialize method for example) that in some way violates the definition of singleton itself.

These days there are better ways to solve this problem and they usually involve other patterns like Service Locator and Dependency Injection. I will describe these patterns in later posts.