Develop a complete use case for software implementing a system for: searching for books on a specific topic using an online bookstore.
> Write a user story for the above software.
> Write a nonfunctional requirement for the application.
Outline your plan addressing these issues and other issues.
Need 6-8 pages APA-formatted paper with minimum of 9 peer-reviewed citations.
84
What is it? Software engineering practice is a broad array of principles, concepts, methods, and tools that you must consider as software is planned and developed. Principles that guide practice establish a foundation from which software engineering is conducted.
Who does it? Practitioners (software engineers) and their managers conduct a variety of soft- ware engineering tasks.
Why is it important? Software process pro- vides everyone involved in the creation of a computer-based system or product with a road map for getting to a successful destina- tion. Software practice provides you with the details you’ll need to drive along the road. It tells you where the bridges, the roadblocks, and the forks are located. It helps you under- stand the concepts and principles that must be understood and followed to drive safely and rapidly. It instructs you on how to drive, where to slow down, and where to speed up. In the context of software engineering, practice is what you do day in and day out as software evolves from an idea to a reality.
What are the steps? Four elements of practice apply regardless of the process model that is chosen. They are principles, concepts, meth- ods, and tools. Tools support the application of methods.
What is the work product? Practice encom- passes the technical activities that produce all work products that are defined by the soft- ware process model that has been chosen.
How do I ensure that I’ve done it right? First, have a firm understanding of the principles that apply to the work (e.g., design) that you’re doing at the moment. Then, be certain that you’ve chosen an appropriate method for the work, be sure that you understand how to apply the method, use automated tools when they’re appropriate for the task, and be adamant about the need for techniques to ensure the quality of work products that are produced. You also need to be agile enough to make changes to your plans and methods as needed.
Q u i c k L o o k
coding principles . . . . . . . . . . . . . . . . . . . . . . . 96 communication principles . . . . . . . . . . . . . . . . 88 core principles . . . . . . . . . . . . . . . . . . . . . . . . . 85 deployment principles . . . . . . . . . . . . . . . . . . 98 modeling principles . . . . . . . . . . . . . . . . . . . . . 92
planning principles . . . . . . . . . . . . . . . . . . . . . 91 practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 testing principles . . . . . . . . . . . . . . . . . . . . . . . 96
k e y c o n c e p t s
C H A P T E R
6 Software engineers are often depicted as working long hours by themselves to meet impossible deadlines without connecting to other people. This is a dark image of software engineering practice to be sure. Yet, as we discussed in the previous chapters, most software engineers work on teams and frequently interact with their stakeholders. If you search for surveys of technical professionals on the Internet, you will see software engineers listed among those experiencing the greatest satisfaction from their jobs.
Principles That Guide Practice
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 85
People who create computer software practice the art or craft or discipline1 that is software engineering. But what is software engineering “practice”? In a generic sense, practice is a collection of concepts, principles, methods, and tools that a software engineer calls upon on a daily basis. Practice allows managers to manage software projects and software engineers to build computer programs. Practice populates a software process model with the necessary technical and management how-to’s to get the job done. Practice transforms a haphazard unfocused approach into something that is more organized, more effective, and more likely to achieve success.
Various aspects of software engineering practice will be examined throughout the remainder of this book. In this chapter, our focus is on principles and concepts that guide software engineering practice in general.
6 .1 co r e pr i nc i p L e s
Software engineering is guided by a collection of core principles that help in the application of a meaningful software process and the execution of effective software engineering methods. At the process level, core principles establish a philosophical foundation that guides a software team as it performs the framework and umbrella activities and produces a set of software engineering work products. At the practice level, core principles establish a collection of values and rules that can guide you in analyzing a problem, designing a solution, implementing and testing the solution, and ultimately deploying the software so stakeholders can use it.
6.1.1 Principles That Guide Process In Part One of this book we discussed the importance of the software process and described several process models that have been proposed for software engineering work. Every project is unique, and every team is unique. That means you must adapt your process to best fit your needs. Regardless of the process model your team adopts, it contains elements of the generic process framework we described in Chapter 1. The following set of core principles can be applied to this framework and to every software process. A simplified view of this framework is shown in Figure 6.1.
Principle 1. Be agile. Whether the process model you choose is prescriptive or agile, the basic tenets of agile development should govern your approach. Every aspect of the work you do should emphasize economy of action—keep your techni- cal approach as simple as possible, keep the work products you produce as concise as possible, and make decisions locally whenever possible.
Principle 2. Focus on quality at every step. The exit condition for every process activity, action, and task should focus on the quality of the work product that has been produced.
Principle 3. Be ready to adapt. Process is not a religious experience, and dogma has no place in it. When necessary, adapt your approach to constraints imposed by the problem, the people, and the project itself.
1 Some writers argue for one of these terms to the exclusion of the others. In reality, software engineering is all three.
86 PART TWO MODELING
Principle 4. Build an effective team. Software engineering process and practice are important, but the bottom line is people. Build a self-organizing team that has mutual trust and respect.2
Principle 5. Establish mechanisms for communication and coordination. Projects fail because important information falls into the cracks and/or stakeholders fail to coordinate their efforts to create a successful end product. These are management issues, and they must be addressed.
Principle 6. Manage change. The approach may be either formal or informal, but mechanisms must be established to manage the way changes are requested, assessed, approved, and implemented.
Principle 7. Assess risk. Lots of things can go wrong as software is being developed. It’s essential that you establish contingency plans. Some of these contingency plans will form the basis for security engineering tasks (Chapter 18).
Principle 8. Create work products that provide value for others. Create only those work products that provide value for other process activities, actions, or tasks. Every work product that is produced as part of software engineering practice will be passed on to someone else. Be sure that the work product imparts the necessary information without ambiguity or omission.
Part Four of this book focuses on project and process management issues and considers various aspects of each of these principles in some detail.
6.1.2 Principles That Guide Practice Software engineering practice has a single overriding goal: to deliver on-time, high- quality, operational software that contains functions and features that meet the needs of all stakeholders. To achieve this goal, you should adopt a set of core principles that guide your technical work. These principles have merit regardless of the analysis
Communication Planning
Construction Deployment
Time
Modeling
Figure 6.1 Simplified process framework
2 The characteristics of effective software teams were discussed in Chapter 5.
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 87
and design methods that you apply, the construction techniques (e.g., programming language, automated tools) that you use, or the verification and validation approach that you choose. The following set of core principles is fundamental to the practice of software engineering:
Principle 1. Divide and conquer. Stated in a more technical manner, analysis and design should always emphasize separation of concerns (SoCs). A large problem is easier to solve if it is subdivided into a collection of elements (or concerns).
Principle 2. Understand the use of abstraction. At its core, an abstraction is a simplification of some complex element of a system used to communicate meaning in a single phrase. When we use the abstraction spreadsheet, it is assumed that you understand what a spreadsheet is, the general structure of content that a spreadsheet presents, and the typical functions that can be applied to it. In software engineering practice, you use many different levels of abstraction, each imparting or implying meaning that must be communicated. In analysis and design work, a software team normally begins with models that represent high levels of abstraction (e.g., a spreadsheet) and slowly refines those models into lower levels of abstraction (e.g., a column or the SUM function).
Principle 3. Strive for consistency. Whether it’s creating an analysis model, developing a software design, generating source code, or creating test cases, the principle of consistency suggests that a familiar context makes software easier to use. As an example, consider the design of a user interface for a mobile app. Consistent placement of menu options, the use of a consistent color scheme, and the consistent use of recognizable icons help to create a highly effective user experience.
Principle 4. Focus on the transfer of information. Software is about information transfer—from a database to an end user, from a legacy system to a WebApp, from an end user into a graphic user interface (GUI), from an operating system to an application, from one software component to another—the list is almost endless. In every case, information flows across an interface, and this means there are opportunities for errors, omissions, or ambiguity. The implication of this principle is that you must pay special attention to the analysis, design, construction, and testing of interfaces.
Principle 5. Build software that exhibits effective modularity. Separation of concerns (Principle 1) establishes a philosophy for software. Modularity provides a mechanism for realizing the philosophy. Any complex system can be divided into modules (components), but good software engineering practice demands more. Modularity must be effective. That is, each module should focus exclusively on one well-constrained aspect of the system. Additionally, modules should be interconnected in a relatively simple manner to other modules, to data sources, and to other environ- mental aspects.
Principle 6. Look for patterns. Software engineers use patterns as a means of cataloging and reusing solutions to problems they have encountered in the past. The use of these design patterns can be applied to wider systems engineering and systems integration problems, by allowing components in complex systems to evolve independently. Patterns will be discussed further in Chapter 14.
Principle 7. When possible, represent the problem and its solution from several different perspectives. When a problem and its solution are examined from different
88 PART TWO MODELING
perspectives, it is more likely that greater insight will be achieved and that errors and omissions will be uncovered. The unified modeling language (UML) provides a means of describing a problem solution from multiple viewpoints, as described in Appendix 1.
Principle 8. Remember that someone will maintain the software. Over the long term, software will be corrected as defects are uncovered, adapted as its environ- ment changes, and enhanced as stakeholders request more capabilities. These main- tenance activities can be facilitated if solid software engineering practice is applied throughout the software process.
These principles are not all you’ll need to build high-quality software, but they do establish a foundation for every software engineering method discussed in this book.
6.2 principLes that Guide each Framework activity
In the sections that follow, we consider principles that have a strong bearing on the success of each generic framework activity defined as part of the software process. In many cases, the principles that are discussed for each of the framework activities are a refinement of the principles presented in Section 6.1. They are simply core principles stated at a lower level of abstraction.
6.2.1 Communication Principles Before customer requirements can be analyzed, modeled, or specified, they must be gathered through the communication activity. A customer has a problem that may be amenable to a computer-based solution. You respond to the customer’s request for help. Communication has begun. But the road from communication to understanding is often full of potholes.
Effective communication (among technical peers, with the customer and other stakeholders, and with project managers) is among the most challenging activities that you will confront. There are many ways to communicate, but it’s important to recog- nize that not all are equal in richness or effectiveness (Figure 6.2). In this context, we discuss communication principles as they apply to customer communication. However, many of the principles apply equally to all forms of communication that occur within a software project.
The Difference Between Customers and End Users A customer is the person or group who
(1) originally requested the software to be built, (2) defines overall business objectives for the software, (3) provides basic product requirements, and (4) coordinates funding for the project. In a product or system business, the customer is often the marketing group. In an information technology
(IT) environment, the customer might be a business component or department.
An end user is the person or group who (1) will actually use the software that is built to achieve some business purpose and (2) will define opera- tional details of the software so the business purpose can be achieved. In some cases, the customer and the end user may be one and the same, but for many projects that is not the case.
inFo
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 89
Principle 1. Listen. Before communicating, be sure you understand the point of view of the other party, know a bit about his or her needs, and then listen. Try to focus on the speaker’s words, rather than formulating your response to those words. Ask for clarification if something is unclear, and avoid constant interruptions. Never become contentious in your words or actions (e.g., rolling your eyes or shaking your head) as a person is talking.
Principle 2. Prepare before you communicate. Spend the time to understand the problem before you meet with others. If necessary, do some research to understand business domain jargon. If you have responsibility for conducting a meeting, prepare an agenda in advance of the meeting.
Principle 3. Someone should facilitate the activity. Every communication meeting should have a leader (a facilitator) to keep the conversation moving in a productive direction, (2) to mediate any conflict that does occur, and (3) to ensure that other principles are followed.
Principle 4. Face-to-face communication is best. However, this communication usually works better when some other representation of the relevant information is present. For example, a participant may create a drawing or a “strawman” document that serves as a focus for discussion.
Principle 5. Take notes and document decisions. Things have a way of falling into the cracks. Someone participating in the communication should serve as a “recorder” and write down all important points and decisions.
Principle 6. Strive for collaboration. Collaboration and consensus occur when the collective knowledge of members of the team is used to describe product or system functions or features. Each small collaboration serves to build trust among team members and creates a common goal for the team.
E-mail Text
Telephone
Video-conference
Face-to-face
Richness of Communication
C om
m un
ic at
io n
E� ec
tiv en
es s
Paper
Figure 6.2 Effectiveness of communication modes
90 PART TWO MODELING
Principle 7. Stay focused; modularize your discussion. The more people are involved in any communication, the more likely that discussion will bounce from one topic to the next. The facilitator should keep the conversation modular, leaving one topic only after it has been resolved (however, see Principle 9).
Principle 8. If something is unclear, draw a picture. Verbal communication goes only so far. A sketch or drawing can often provide clarity when words fail to do the job.
Principle 9. (a) Once you agree to something, move on. (b) If you can’t agree to something, move on. (c) If a feature or function is unclear and cannot be clarified right now, move on. Communication, like any software engineering activity, takes time. Rather than iterating endlessly, the people who participate should recognize that many topics require discussion (see Principle 2) and that “moving on” is sometimes the best way to achieve communication agility.
Principle 10. Negotiation is not a contest or a game. It works best when both parties win. There are many instances in which you and other stakeholders must negotiate functions and features, priorities, and delivery dates. If the team has collaborated well, all parties have a common goal. Still, negotiation will demand compromise from all parties.
Communication Mistakes
The scene: Software engineer- ing team workspace
The players: Jamie Lazar, software team member; Vinod Raman, software team member; Ed Robbins, software team member.
The conversation: Ed: What have you heard about this SafeHome project?
Vinod: The kickoff meeting is scheduled for next week.
Jamie: I’ve already done a little bit of investi- gation, but it didn’t go well.
Ed: What do you mean?
Jamie: Well, I gave Lisa Perez a call. She’s the marketing honcho on this thing.
Vinod: And . . . ?
Jamie: I wanted her to tell me about SafeHome features and functions . . . that sort of thing. Instead, she began asking me questions about security systems, surveillance systems . . . I’m no expert.
Vinod: What does that tell you?
(Jamie shrugs)
Vinod: That marketing will need us to act as consultants and that we’d better do some homework on this product area before our kickoff meeting. Doug said that he wanted us to “collaborate” with our customer, so we’d better learn how to do that.
Ed: Probably would have been better to stop by her office. Phone calls just don’t work as well for this sort of thing.
Jamie: You’re both right. We’ve got to get our act together or our early communications will be a struggle.
Vinod: I saw Doug reading a book on “requirements engineering.” I’ll bet that lists some principles of good communication. I’m going to borrow it from him.
Jamie: Good idea . . . then you can teach us.
Vinod (smiling): Yeah, right.
saFehome
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 91
6.2.2 Planning Principles The planning activity encompasses a set of management and technical practices that enable the software team to define a road map as it travels toward its strategic goal and tactical objectives.
Try as we might, it’s impossible to predict exactly how a software project will evolve. There is no easy way to determine what unforeseen technical problems will be encountered, what important information will remain undiscovered until late in the project, what misunderstandings will occur, or what business issues will change. And yet, a good software team must plan its approach. Often planning is iterative (Figure 6.3).
There are different planning philosophies.3 Some people are “minimalists,” arguing that change often obviates the need for a detailed plan. Others are “traditionalists,” arguing that the plan provides an effective road map and the more detail it has, the less likely the team will become lost.
What to do? On many projects, overplanning is time consuming and fruitless (too many things change), but underplanning is a recipe for chaos. Like most things in life, planning should be agile and conducted in moderation, enough to provide useful guid- ance for the team—no more, no less. Regardless of the rigor with which planning is conducted, the following principles always apply:
Principle 1. Understand the scope of the project. It’s impossible to use a road map if you don’t know where you’re going. Scope provides the software team with a destination.
Principle 2. Involve stakeholders in the planning activity. Stakeholders define priorities and establish project constraints. To accommodate these realities, software engineers must often negotiate order of delivery, time lines, and other project- related issues.
3 A detailed discussion of software project planning and management is presented in Part Four of this book.
Initial risks and project scope
Identify the highest risks
Plan and develop
Assess
Iteration N
Risk eliminated
Revise risk assessment
Revise project plan
Figure 6.3 Iterative planning
92 PART TWO MODELING
Principle 3. Recognize that planning is iterative. A project plan is never engraved in stone. As work begins, it is very likely that things will change. The plan will need to be adjusted. Iterative, incremental process models include time for revising plans after the delivery of each software increment based on feedback received from users.
Principle 4. Estimate based on what you know. The intent of estimation is to provide an indication of effort, cost, and task duration, based on the team’s current understanding of the work to be done. If information is vague or unreliable, estimates will be equally unreliable.
Principle 5. Consider risk as you define the plan. If you have identified risks that have high impact and high probability, contingency planning is necessary. The project plan (including the schedule) should be adjusted to accommodate the likelihood that one or more of these risks will occur.
Principle 6. Be realistic. People don’t work 100 percent of every day. Changes will occur. Even the best software engineers make mistakes. These and other realities should be considered as a project plan is established.
Principle 7. Adjust granularity as you define the plan. The term granularity refers to the detail with which some element of planning is represented or conducted. A high-granularity plan provides significant work task detail that is planned over relatively short time increments (so that tracking and control occur frequently). A low-granularity plan provides broader work tasks that are planned over longer time periods. In general, granularity moves from high to low as the project time line moves away from the current date. Activities that won’t occur for many months do not require high granularity (too much can change).
Principle 8. Define how you intend to ensure quality. The plan should identify how the software team intends to ensure quality. If technical reviews4 are to be conducted, they should be scheduled. If pair programming (Chapter 3) is to be used during construction, it should be explicitly defined within the plan.
Principle 9. Describe how you intend to accommodate change. Uncontrolled change can obviate even the best planning. You should identify how changes are to be accommodated as software engineering work proceeds. For example, can the customer request a change at any time? If a change is requested, is the team obliged to implement it immediately? How is the impact and cost of the change assessed?
Principle 10. Track the plan frequently, and make adjustments as required. Software projects fall behind schedule one day at a time. Therefore, it makes sense to track progress daily, looking for problem areas and situations in which scheduled work does not conform to actual work conducted. When slippage is encountered, the plan is adjusted accordingly.
To be most effective, everyone on the software team should participate in the planning activity. Only then will team members “sign up” to the plan.
6.2.3 Modeling Principles We create models to gain a better understanding of the actual entity to be built. When the entity is a physical thing (e.g., a building, a plane, a machine), we can build a
4 Technical reviews are discussed in Chapter 16.
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 93
three-dimensional (3D) model that is identical in form and shape but smaller in scale. However, when the entity to be built is software, our model must take a different form. It must be capable of representing the information that software transforms, the architecture and functions that enable the transformation to occur, the features that users desire, and the behavior of the system as the transformation is taking place. Models must accomplish these objectives at different levels of abstraction—first depicting the software from the customer’s viewpoint and later representing the soft- ware at a more technical level. Figure 6.4 shows how modeling may be used in agile software design.
In software engineering work, two classes of models can be created: requirements models and design models. Requirements models (also called analysis models) repre- sent customer requirements by depicting the software in three different domains: the information domain, the functional domain, and the behavioral domain (Chapter 8). Design models represent characteristics of the software that help practitioners to con- struct it effectively: the architecture, the user interface, and component-level detail (Chapters 9 through 12).
In their book on agile modeling, Scott Ambler and Ron Jeffries [Amb02] define a set of modeling principles5 that are intended for those who use an agile process model (Chapter 3) but are appropriate for all software engineers who perform modeling action and tasks:
Principle 1. The primary goal of the software team is to build software, not create models. Agility means getting software to the customer in the fastest possible time. Models that make this happen are worth creating, but models that slow the process down or provide little new insight should be avoided.
Modeling Quick Design
Quick Design
Deployment, Delivery, Feedback
Communication
Construction of Prototype
Figure 6.4 Role of software modeling
5 The principles noted in this section have been abbreviated and rephrased for the purposes of this book.
94 PART TWO MODELING
Principle 2. Travel light—don’t create more models than you need. Every model that is created must be kept up to date as changes occur. More importantly, every new model takes time that might otherwise be spent on construction (coding and testing). Therefore, create only those models that make it easier and faster to construct the software.
Principle 3. Strive to produce the simplest model that will describe the prob- lem or the software. Don’t overbuild the software [Amb02]. By keeping models simple, the resultant software will also be simple. The result is software that is easier to integrate, easier to test, and easier to maintain (to change). In addition, simple models are easier for members of the software team to understand and critique, resulting in an ongoing form of feedback that optimizes the end result.
Principle 4. Build models in a way that makes them amenable to change. Assume that your models will change, but in making this assumption don’t get sloppy. The problem with this attitude is that you may not create a reasonably complete requirements model, which means you’ll create a design (design model) that will invariably miss important functions and features.
Principle 5. Be able to state an explicit purpose for each model that is created. Every time you create a model, ask yourself why you’re doing so. If you can’t provide solid justification for the existence of the model, don’t spend time on it.
Principle 6. Adapt the models you develop to the system at hand. It may be necessary to adapt model notation or rules to the application; for example, a video game application might require a different modeling technique than real-time, embedded software for adaptive cruise control in an automobile.
Principle 7. Try to build useful models, but forget about building perfect models. When building requirements and design models, a software engineer reaches a point of diminishing returns. That is, the effort required to make a model that is complete and internally consistent may not be worth the benefits of these properties. Iterating endlessly to make a model “perfect” does not serve the need for agility.
Principle 8. Don’t become dogmatic about the syntax of the model. If it communi- cates content successfully, representation is secondary. Although everyone on a soft- ware team should try to use consistent notation during modeling, the most important characteristic of the model is to communicate information that enables the next software engineering task. If a model does this successfully, incorrect syntax can be forgiven.
Principle 9. If your instincts tell you a model isn’t right even though it seems okay on paper, you probably have reason to be concerned. If you are an experi- enced software engineer, trust your instincts. Software work teaches many lessons— some of them on a subconscious level. If something tells you that a design model is doomed to fail (even though you can’t prove it explicitly), you have reason to spend additional time examining the model or developing a different one.
Principle 10. Get feedback as soon as you can. The intent of any model is to communicate information. It should stand on its own. Assume that you won’t be there to explain the model. Every model should be reviewed by members of the software team. The intent of these reviews is to provide feedback that can be used to correct modeling mistakes, change misinterpretations, and add features or functions that were inadvertently omitted.
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 95
6.2.4 Construction Principles The construction activity encompasses a set of coding and testing tasks that lead to operational software that is ready for delivery to the customer or end user.
In modern software engineering work, coding may be: (1) the direct creation of programming language source code, (2) the automatic generation of source code using an intermediate design like representation of the component to be built, or (3) the automatic generation of executable code using a fourth-generation programming lan- guage (e.g., Unreal4 Blueprints).6
The initial focus of testing is at the component level, often called unit testing. Other levels of testing include (1) integration testing (conducted as the system is con- structed), (2) validation testing that assesses whether requirements have been met for the complete system (or software increment), and (3) acceptance testing that is con- ducted by the customer in an effort to exercise all required features and functions. Figure 6.5 shows where testing and test case design is placed in agile processes.
Testing is considered in detail in Chapters 19 through 21. The following set of fundamental principles and concepts are applicable to coding and testing.
6 Blueprints is a visual scripting tool created by Epic Games (https://docs.unrealengine.com/ latest/INT/Engine/Blueprints/).
Accept?
Feedback & Review
Mock-ups Design
Development
Document & Review
Evaluate & Test
Evaluate & Test
Release
Acceptance Testing
User Stories
Yes
No
Figure 6.5 Testing in agile processes
96 PART TWO MODELING
Coding Principles. The principles that guide the coding task are closely aligned with programming style, programming languages, and programming methods. There are some fundamental principles that might be followed:
Preparation Principles: Before you write one line of code, be sure you:
Principle 1. Understand the problem you’re trying to solve.
Principle 2. Understand basic design principles and concepts.
Principle 3. Pick a programming language that meets the needs of the software to be built and the environment in which it will operate.
Principle 4. Select a programming environment that provides tools that will make your work easier.
Principle 5. Create a set of unit tests that will be applied once the component you code is completed.
Coding Principles: As you begin writing code, be sure you:
Principle 6. Constrain your algorithms by following structured programming [Boh00] practice.
Principle 7. Consider the use of pair programming.
Principle 8. Select data structures that will meet the needs of the design.
Principle 9. Understand the software architecture and create interfaces that are consistent with it.
Validation Principles: After you’ve completed your first coding pass, be sure you:
Principle 10. Conduct a code walkthrough when appropriate.
Principle 11. Perform unit tests and correct errors you’ve uncovered.
Principle 12. Refactor the code to improve its quality.
Testing Principles. In a classic book on software testing, Glen Myers [Mye79] states a number of rules that can serve well as testing objectives:
1. Testing is a process of executing a program with the intent of finding an error.
2. A good test case is one that has a high probability of finding an as-yet- undiscovered error.
3. A successful test is one that uncovers an as-yet-undiscovered error.
These objectives imply a dramatic change in viewpoint for some software developers. They move counter to the commonly held view that a successful test is one in which no errors are found. Your objective is to design tests that systematically uncover dif- ferent classes of errors and to do so with a minimum amount of time and effort.
As a secondary benefit, testing demonstrates that software functions appear to be working according to specification and that behavioral and performance requirements appear to have been met. In addition, the data collected as testing is conducted provide a good indication of software reliability and some indication of software quality.
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 97
Testing cannot show the absence of errors and defects; it can show only that software errors and defects are present (Figure 6.6). It is important to keep this (rather gloomy) statement in mind as testing is being conducted.
Davis [Dav95b] suggests a set of testing principles7 that have been adapted for use in this book. In addition, Everett and Meyer [Eve09] suggest additional principles:
Principle 1. All tests should be traceable to customer requirements.8 The objec- tive of software testing is to uncover errors. It follows that the most severe defects (from the customer’s point of view) are those that cause the program to fail to meet its requirements.
Principle 2. Tests should be planned long before testing begins. Test planning (Chapter 19) can begin as soon as the requirements model is complete. Detailed def- inition of test cases can begin as soon as the design model has been solidified. Therefore, all tests can be planned and designed before any code has been generated.
Principle 3. The Pareto principle applies to software testing. In this context, the Pareto principle implies that 80 percent of all errors uncovered during testing will
7 Only a small subset of Davis’s testing principles are noted here. For more information, see [Dav95b].
8 This principle refers to functional tests, that is, tests that focus on requirements. Structural tests (tests that focus on architectural or logical detail) may not address specific requirements directly.
We ran our tests and did not find
any errors!
Figure 6.6 Testing is never complete
98 PART TWO MODELING
likely be traceable to 20 percent of all program components. The problem, of course, is to isolate these suspect components and to thoroughly test them.
Principle 4. Testing should begin “in the small” and progress toward testing “in the large.” The first tests planned and executed generally focus on individual components. As testing progresses, focus shifts to looking for errors in integrated clusters of components and ultimately in the entire system.
Principle 5. Exhaustive testing is not possible. The number of path permutations for even a moderately sized program is exceptionally large. For this reason, it is impossible to execute every combination of paths during testing. It is possible, however, to adequately cover program logic and to ensure that all conditions in the component-level design have been exercised.
Principle 6. Apply to each module in the system a testing effort commensurate with its expected fault density. These are often the newest modules or the ones that are least understood by the developers.
Principle 7. Static testing techniques can yield high results. More than 85 per- cent of software defects originate in the software documentation (requirements, specifications, code walk-throughs, and user manuals) [Jon91]. There may be value in testing the system documentation.
Principle 8. Track defects and look for patterns in defects uncovered by testing. The total defects uncovered is a good indicator of software quality. The types of defects uncovered can be a good measure of software stability. Patterns of defects found over time can forecast numbers of expected defects.
Principle 9. Include test cases that demonstrate software is behaving correctly. As software components are being maintained or adapted, unexpected interactions cause unintended side effects in other components. It is important to have a set of regression test cases (Chapter 19) ready to check system behavior after changes are made to a software product.
6.2.5 Deployment Principles As we noted in Part One of this book, the deployment activity encompasses three actions: delivery, support, and feedback. Because modern software process models are evolutionary or incremental in nature, deployment happens not once, but several times as software moves toward completion. Each delivery cycle provides the cus- tomer and end users with an operational software increment that provides usable functions and features. Each support cycle provides documentation and human assis- tance for all functions and features introduced during all deployment cycles to date. Each feedback cycle provides the software team with important guidance that results in modifications to the functions, features, and approach taken for the next increment. Typical deployment actions are illustrated in Figure 6.7.
The delivery of a software increment represents an important milestone for any software project. Some key principles should be followed as the team prepares to deliver an increment:
Principle 1. Customer expectations for the software must be managed. Too often, the customer expects more than the team has promised to deliver, and disappointment
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 99
occurs immediately. This results in feedback that is not productive and ruins team morale. In her book on managing expectations, Naomi Karten [Kar94] states: “The starting point for managing expectations is to become more conscientious about what you communicate and how.” She suggests that a software engineer must be careful about sending the customer conflicting messages (e.g., promising more than you can reasonably deliver in the time period provided or delivering more than you promise for one software increment and then less than promised for the next).
Principle 2. A complete delivery package should be assembled and tested. All executable software, support data files, support documents, and other relevant information should be assembled and thoroughly beta-tested with actual users. All installation scripts and other operational features should be thoroughly exercised in all possible computing configurations (i.e., hardware, operating systems, peripheral devices, networking arrangements).
Principle 3. A support regimen must be established before the software is delivered. An end user expects responsiveness and accurate information when a question or problem arises. If support is ad hoc, or worse, nonexistent, the customer will become dissatisfied immediately. Support should be planned, support materials should be prepared, and appropriate record-keeping mechanisms should be established so that the software team can conduct a categorical assessment of the kinds of support requested.
Principle 4. Appropriate instructional materials must be provided to end users. The software team delivers more than the software itself. Appropriate training aids (if required) should be developed; troubleshooting guidelines should be provided,
Assemble Deployment Package Establish Support Regimen
Manage Customer Expectations Provide Instructional Materials to End Users
Figure 6.7 Deployment actions
100 PART TWO MODELING
and when necessary, a “what’s different about this software increment” description should be published.9
Principle 5. Buggy software should be fixed first, delivered later. Under time pressure, some software organizations deliver low-quality increments with a warning to the customer that bugs “will be fixed in the next release.” This is a mistake. There’s a saying in the software business: “Customers will forget you delivered a high-quality product a few days late, but they will never forget the problems that a low-quality product caused them. The software reminds them every day.”
6 .3 su m m a ry
Software engineering practice encompasses principles, concepts, methods, and tools that software engineers apply throughout the software process. Every software engi- neering project is different. Yet, a set of generic principles applies to the process and to the practice of each framework activity regardless of the project or the product.
A set of core principles helps in the application of a meaningful software process and the execution of effective software engineering methods. At the process level, core principles establish a philosophical foundation that guides a software team as it navigates through the software process. At the practice level, core principles establish a collection of values and rules that serve as a guide as you analyze a problem, design a solution, implement and test the solution, and ultimately deploy the software in the user community.
Communication principles focus on the need to reduce noise and improve band- width as the conversation between developer and customer progresses. Both parties must collaborate for the best communication to occur.
Planning principles provide guidelines for constructing the best map for the journey to a completed system or product. The plan may be designed solely for a single soft- ware increment, or it may be defined for the entire project. Regardless, it must address what will be done, who will do it, and when the work will be completed.
Modeling principles serve as a foundation for the methods and notation that are used to create representations of the software. Modeling encompasses both analysis and design, describing representations of the software that progressively become more detailed. The intent of the models is to solidify understanding of the work to be done and to provide technical guidance to those who will implement the software.
Construction incorporates a coding and testing cycle in which source code for a component is generated and tested. Coding principles define generic actions that should occur before code is written, while it is being created, and after it has been completed. Although there are many testing principles, only one is dominant: Testing is a process of executing a program with the intent of finding an error.
Deployment occurs as each software increment is presented to the customer and encompasses delivery, support, and feedback. Key principles for delivery consider managing customer expectations and providing the customer with appropriate support
9 During the communication activity, the software team should determine what types of help materials users want.
CHAPTER 6 PRINCIPLES THAT GUIDE PRACTICE 101
information for the software. Support demands advance preparation. Feedback allows the customer to suggest changes that have business value and provide the developer with input for the next iterative software engineering cycle.
Pro b l e m s a n d Po i n t s to Po n d e r
6.1. Because a focus on quality demands resources and time, is it possible to be agile and still maintain a quality focus?
6.2. Of the eight core principles that guide process (discussed in Section 6.1.1), which do you believe is most important?
6.3. Describe the concept of separation of concerns in your own words.
6.4. Why is it necessary to “move on”?
6.5. Do some research on “negotiation” for the communication activity, and prepare a set of guidelines that focus solely on negotiation.
6.6. Why are models important in software engineering work? Are they always necessary? Are there qualifiers to your answer about necessity?
6.7. What is a successful test?
6.8. Why is feedback important to the software team?
Design element: Quick Look icon magnifying glass: © Roger Pressman
102
What is it? Before you begin any technical work, it’s a good idea to create a set of requirements for the engineering tasks. By establishing a set of requirements, you’ll gain an understanding of what the business impact of the software will be, what the customer wants, and how end users will interact with the software.
Who does it? Software engineers and other project stakeholders (managers, customers, and end users) all participate in requirements engineering.
Why is it important? To understand what the customer wants before you begin to design and build a computer-based system. Building an elegant computer program that solves the wrong problem helps no one.
What are the steps? Requirements engineer- ing begins with inception (a task that defines the scope and nature of the problem to be solved). It moves onward to elicitation (a task that helps stakeholders define what is
required), and then elaboration (where basic requirements are refined and modified). As stakeholders define the problem, negotiation occurs (what are the priorities, what is essen- tial, when is it required?). Finally, the problem is specified in some manner and then re- viewed or validated to ensure that your under- standing of the problem and the stakeholders’ understanding of the problem coincide.
What is the work product? Requirements en- gineering provides all parties with a written understanding of the problem. The work prod- ucts may include: usage scenarios, function and feature lists, and requirements models.
How do I ensure that I’ve done it right? Re- quirements engineering work products are reviewed with stakeholders to ensure that ev- eryone is on the same page. A word of warn- ing: Even after all parties agree, things will change, and they will continue to change throughout the project.
Q u i c k L o o k
analysis model . . . . . . . . . . . . . . . . . . . . . . . . 118 analysis patterns . . . . . . . . . . . . . . . . . . . . . . 122 collaboration . . . . . . . . . . . . . . . . . . . . . . . . . 108 elaboration . . . . . . . . . . . . . . . . . . . . . . . . . . 104 elicitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 inception . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . 105 requirements engineering . . . . . . . . . . . . . . 103 requirements gathering . . . . . . . . . . . . . . . . 110
requirements management . . . . . . . . . . . . . 106 requirements monitoring . . . . . . . . . . . . . . . 123 specification . . . . . . . . . . . . . . . . . . . . . . . . . 105 stakeholders . . . . . . . . . . . . . . . . . . . . . . . . . 107 use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 validating requirements . . . . . . . . . . . . . . . . 123 validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 viewpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 work products . . . . . . . . . . . . . . . . . . . . . . . . 114
k e y c o n c e p t s
C H A P T E R
7 Understanding problem requirements is among the most difficult tasks facing a software engineer. When you first think about it, developing a clear understand- ing of the requirements doesn’t seem that hard. After all, doesn’t the customer know what is required? Shouldn’t the end users have a good understanding of the features and functions that they need? Surprisingly, in many instances, the answer to these questions is no. And even if customers and end users can state their needs explicitly, those needs will change throughout the project.
Understanding Requirements
CHAPTER 7 UNDERSTANDING REQUIREMENTS 103
In the forward to a book by Ralph Young [You01] on effective requirements prac- tices, one of us [RSP] wrote:
It’s your worst nightmare. A customer walks into your office, sits down, looks you straight in the eye, and says, “I know you think you understand what I said, but what you don’t understand is what I said is not what I meant.” Invariably, this happens late in the project, after deadline commitments have been made, reputations are on the line, and serious money is at stake.
All of us who have worked in the systems and software business for more than a few years have lived this nightmare, and yet, few of us have learned to make it go away. We struggle when we try to elicit requirements from our customers. We have trouble under- standing the information that we do acquire. We often record requirements in a disorga- nized manner, and we spend far too little time verifying what we do record. We allow change to control us, rather than establishing mechanisms to control change. In short, we fail to establish a solid foundation for the system or software. Each of these problems is challenging. When they are combined, the outlook is daunting for even the most experienced managers and practitioners. But solutions do exist.
It’s reasonable to argue that the techniques we’ll discuss in this chapter are not a true “solution” to the challenges just noted. But they do provide a solid approach for addressing these challenges.
7 .1 Re Q u i R e m e n t s eng i n e e R i ng
Designing and building computer software is challenging, creative, and just plain fun. In fact, building software is so compelling that many software developers want to jump right in before they have a clear understanding of what is needed. They argue that things will become clear as they build, that project stakeholders will be able to understand need only after examining early iterations of the software, that things change so rapidly that any attempt to understand requirements in detail is a waste of time, that the bottom line is producing a working program, and that all else is second- ary. What makes these arguments seductive is that they contain elements of truth. But each argument is flawed and can lead to a failed software project.
Requirements engineering is the term for the broad spectrum of tasks and tech- niques that lead to an understanding of requirements. From a software process per- spective, requirements engineering is a major software engineering action that begins during the communication activity and continues into the modeling activity. Require- ments engineering establishes a solid base for design and construction. Without it, the resulting software has a high probability of not meeting customer’s needs. It must be adapted to the needs of the process, the project, the product, and the people doing the work. It is important to realize that each of these tasks is done iteratively as the project team and the stakeholders continue to share information about their respective concerns.
Requirements engineering builds a bridge to design and construction. But where does the bridge originate? One could argue that it begins with the project stakehold- ers (e.g., managers, customers, and end users), where business needs are defined, user scenarios are described, functions and features are delineated, and project constraints are identified. Others might suggest that it begins with a broader system definition,
104 PART TWO MODELING
where software is but one component of the larger system domain. But regardless of the starting point, the journey across the bridge takes you high above the project, allowing you to examine the context of the software work to be performed; the specific needs that design and construction must address; the priorities that guide the order in which work is to be completed; and the information, functions, and behaviors that will have a profound impact on the resulting design. Requirements engineering encompasses seven tasks with sometimes muddy boundaries: inception, elicitation, elaboration, negotiation, specification, validation, and management. It is important to note that some of these tasks occur in parallel and all are adapted to the needs of the project. Expect to do a bit of design during requirements work and a bit of requirements work during design.
7.1.1 Inception How does a software project get started? In general, most projects begin with an identified business need or when a potential new market or service is discovered. At project inception, you establish a basic understanding of the problem, the people who want a solution, and the nature of the solution that is desired. Communication between all stakeholders and the software team needs to be established during this task to begin an effective collaboration.
7.1.2 Elicitation It certainly seems simple enough—ask the customer, the users, and others what the objectives for the system or product are, what is to be accomplished, how the system or product fits into the needs of the business, and finally, how the system or product is to be used on a day-to-day basis. But it isn’t simple—it’s very hard.
An important part of elicitation is to understand the business goals [Cle10]. A goal is a long-term aim that a system or product must achieve. Goals may deal with either functional or nonfunctional (e.g., reliability, security, usability) concerns [Lam09].
Goals are often a good way to explain requirements to stakeholders and, once established, can be used to manage conflicts among stakeholders. Goals should be specified precisely and serve as the basis for requirements elaboration, verification and validation, conflict management, negotiation, explanation, and evolution.
Your job is to engage stakeholders and to encourage them to share their goals honestly. Once the goals are captured, you establish a prioritization mechanism and create a design rationale for a potential architecture (that meets stakeholder goals).
Agility is an important aspect of requirements engineering. The intent of elicitation is to transfer ideas from stakeholders to the software team smoothly and without delay. It is highly likely that new requirements will continue to emerge as iterative product development occurs.
7.1.3 Elaboration The elaboration task focuses on developing a refined requirements model that identifies various aspects of software function, behavior, and information (Chapter 8). Elabora- tion is driven by the creation and refinement of user scenarios obtained during elicita- tion. These scenarios describe how the end users (and other actors) will interact with the system. Each user scenario is parsed to extract analysis classes—business domain
CHAPTER 7 UNDERSTANDING REQUIREMENTS 105
entities that are visible to the end user. The attributes of each analysis class are defined, and the services that are required by each class are identified. The relationships and collaboration between classes are identified. Elaboration is a good thing, but you need to know when to stop. The key is to describe the problem in a way that establishes a firm base for design and then move on. Do not obsess over unnecessary details.
7.1.4 Negotiation It isn’t unusual for customers and users to ask for more than can be achieved, given limited business resources. It’s also relatively common for different customers or users to propose conflicting requirements, arguing that their version is “essential for our special needs.”
These conflicts need to be reconciled through the process of negotiation. Custom- ers, users, and other stakeholders are asked to rank requirements and then discuss conflicts in priority. There should be no winner and no loser in an effective negotia- tion. Both sides win, because a “deal” that both can live with is solidified. You should use an iterative approach that prioritizes requirements, assesses their cost and risk, and addresses internal conflicts. In this way, requirements are eliminated, combined, and/or modified so that each party achieves some measure of satisfaction.
7.1.5 Specification In the context of computer-based systems (and software), the term specification means different things to different people. A specification can be a written document, a set of graphical models, a formal mathematical model, a collection of usage scenarios, a prototype, or any combination of these.
Some suggest that a “standard template” [Som97] should be developed and used for a specification, arguing that this leads to requirements that are presented in a consistent and therefore more understandable manner. However, it is sometimes necessary to remain flexible when a specification is to be developed. The formality and format of a specification varies with the size and the complexity of the software to be built. For large systems, a written document, combining natural language descriptions and graph- ical models, may be the best approach. A template for a formal software requirements specification document can be downloaded from: https://web.cs.dal.ca/~hawkey/3130/ srs_template-ieee.doc. However, usage scenarios may be all that are required for smaller products or systems that reside within well-understood technical environments.
7.1.6 Validation The work products produced during requirements engineering are assessed for quality during a validation step. A key concern during requirements validation is consistency. Use the analysis model to ensure that requirements have been consistently stated. Requirements validation examines the specification to ensure that all software require- ments have been stated unambiguously; that inconsistencies, omissions, and errors have been detected and corrected; and that the work products conform to the standards established for the process, the project, and the product.
The primary requirements validation mechanism is the technical review (Chapter 16). The review team that validates requirements includes software engineers, customers, users, and other stakeholders who examine the specification looking for errors in
106 PART TWO MODELING
content or interpretation, areas where clarification may be required, missing informa- tion, inconsistencies (a major problem when large products or systems are engineered), conflicting requirements, or unrealistic (unachievable) requirements.
To illustrate some of the problems that occur during requirements validation, consider two seemingly innocuous requirements:
∙ The software should be user friendly. ∙ The probability of a successful unauthorized database intrusion should be less
than 0.0001. The first requirement is too vague for developers to test or assess. What exactly
does “user friendly” mean? To validate it, it must be quantified or qualified in some manner.
The second requirement has a quantitative element (“less than 0.0001”), but intru- sion testing will be difficult and time consuming. Is this level of security even war- ranted for the application? Can other complementary requirements associated with security (e.g., password protection, specialized handshaking) replace the quantitative requirement noted?
7.1.7 Requirements Management Requirements for computer-based systems change, and the desire to change require- ments persists throughout the life of the system. Requirements management is a set of activities that help the project team identify, control, and track requirements and changes to requirements at any time as the project proceeds. Many of these activities are identical to the software configuration management (SCM) techniques discussed in Chapter 22.
Requirements Validation Checklist It is often useful to examine each re-
quirement against a set of checklist questions. Here is a small subset of those that might be asked:
1. Are requirements stated clearly? Can they be misinterpreted?
2. Is the source (e.g., a person, a regulation, a document) of the requirement identified? Has the final statement of the requirement been examined by or against the original source?
3. Is the requirement bounded in quantitative terms?
4. What other requirements relate to this re- quirement? Are they clearly noted via a cross-reference matrix or other mechanism?
5. Does the requirement violate any system domain constraints?
6. Is the requirement testable? If so, can we specify tests (sometimes called validation criteria) to exercise the requirement?
7. Is the requirement traceable to any system model that has been created?
8. Is the requirement traceable to overall system and product objectives?
9. Is the specification structured in a way that leads to easy understanding, easy reference, and easy translation into more technical work products?
10. Has an index for the specification been created?
11. Have requirements associated with perfor- mance, behavior, and operational character- istics been clearly stated? What requirements appear to be implicit?
info
CHAPTER 7 UNDERSTANDING REQUIREMENTS 107
7 .2 esta b L i s h i ng t h e gRo u n dwo R k
In an ideal setting, stakeholders and software engineers work together on the same team. In such cases, requirements engineering is simply a matter of conducting mean- ingful conversations with colleagues who are well-known members of the team. But reality is often quite different.
Customer(s) or end users may reside in different cities or countries, may have only a vague idea of what is required, may have conflicting opinions about the system to be built, may have limited technical knowledge, and may have limited time to interact with the requirements engineer. None of these things are desirable, but all are com- mon, and you are often forced to work within the constraints imposed by this situation.
In the sections that follow, we discuss the steps required to establish the ground- work for an understanding of software requirements—to get the project started in a way that will keep it moving forward toward a successful solution.
7.2.1 Identifying Stakeholders Sommerville and Sawyer [Som97] define a stakeholder as “anyone who benefits in a direct or indirect way from the system which is being developed.” We have already identified the usual suspects: business operations managers, product managers, market- ing people, internal and external customers, end users, consultants, product engineers, software engineers, support and maintenance engineers, and others. Each stakeholder has a different view of the system, achieves different benefits when the system is suc- cessfully developed, and is open to different risks if the development effort should fail.
At inception, you should create a list of people who will contribute input as require- ments are elicited (Section 7.3). The initial list will grow as stakeholders are contacted because every stakeholder will be asked: “Whom else do you think I should talk to?”
7.2.2 Recognizing Multiple Viewpoints Because many different stakeholders exist, the requirements of the system will be explored from many different points of view. For example, the marketing group is interested in features that will excite the potential market, making the new system easy to sell. Business managers are interested in a feature set that can be built within budget and that will be ready to meet defined market windows. End users may want features that are familiar to them and that are easy to learn and use. Software engineers may be concerned with functions that are invisible to nontechnical stakeholders but that enable an infrastructure that supports more marketable functions and features. Support engineers may focus on the maintainability of the software.
Each of these constituencies (and others) will contribute information to the require- ments engineering process. As information from multiple viewpoints is collected, emerging requirements may be inconsistent or may conflict with one another. You should categorize all stakeholder information (including inconsistent and conflicting requirements) in a way that will allow decision makers to choose an internally con- sistent set of requirements for the system.
Several things can make it hard to elicit requirements for software that satisfies its users: project goals are unclear, stakeholders’ priorities differ, people have unspoken assumptions, stakeholders interpret meanings differently, and requirements are stated in a way that makes them difficult to verify [Ale11]. The goal of effective require- ments engineering is to eliminate or at least reduce these problems.
108 PART TWO MODELING
7.2.3 Working Toward Collaboration If five stakeholders are involved in a software project, you may have five (or more) different opinions about the proper set of requirements. Throughout earlier chapters, we have noted that customers (and other stakeholders) should collaborate among themselves (avoiding petty turf battles) and with software engineering practitioners if a successful system is to result. But how is this collaboration accomplished?
The job of a requirements engineer is to identify areas of commonality (i.e., requirements on which all stakeholders agree) and areas of conflict or inconsistency (i.e., requirements that are desired by one stakeholder but conflict with the needs of another stakeholder). It is, of course, the latter category that presents a challenge.
Collaboration does not necessarily mean that requirements are “defined by com- mittee.” In many cases, stakeholders collaborate by providing their view of require- ments, but a strong “project champion” (e.g., a business manager or a senior technologist) may make the final decision about which requirements make the cut.
Using “Planning Poker” One way of resolving conflicting requirements and at the same time
better understanding the relative importance of all requirements is to use a “voting” scheme based on priority points. All stakeholders are provided with some number of priority points that can be “spent” on any number of require- ments. A list of requirements is presented, and
each stakeholder indicates the relative impor- tance of each (from his viewpoint) by spending one or more priority points on it. Points spent cannot be reused. Once a stakeholder’s priority points are exhausted, no further action on requirements can be taken by that person. Overall points spent on each requirement by all stakeholders provide an indication of the overall importance of each requirement.
info
7.2.4 Asking the First Questions Questions asked at the inception of the project should be “context free” [Gau89]. The first set of context-free questions focuses on the customer and other stakeholders and the overall project goals and benefits. For example, you might ask:
∙ Who is behind the request for this work? ∙ Who will use the solution? ∙ What will be the economic benefit of a successful solution? ∙ Is there another source for the solution that you need?
These questions help to identify all stakeholders who will have interest in the software to be built. In addition, the questions identify the measurable benefit of a successful implementation and possible alternatives to custom software development.
The next set of questions enables you to gain a better understanding of the problem and allows the customer to voice her perceptions about a solution:
∙ How would you characterize “good” output that would be generated by a successful solution?
∙ What problem(s) will this solution address?
CHAPTER 7 UNDERSTANDING REQUIREMENTS 109
∙ Can you show me (or describe) the business environment in which the solu- tion will be used?
∙ Will special performance issues or constraints affect the way the solution is approached?
The final set of questions focuses on the effectiveness of the communication activ- ity itself. Gause and Weinberg [Gau89] call these “meta-questions” and propose the following (abbreviated) list:
∙ Are you the right person to answer these questions? Are your answers “official”? ∙ Are my questions relevant to the problem that you have? ∙ Am I asking too many questions? ∙ Can anyone else provide additional information? ∙ Should I be asking you anything else?
These questions (and others) will help to “break the ice” and initiate the commu- nication that is essential to successful elicitation. But a question-and-answer (Q&A) meeting format is not an approach that has been overwhelmingly successful. In fact, the Q&A session should be used for the first encounter only and then replaced by a requirements elicitation format that combines elements of problem solving, negotia- tion, and specification. An approach of this type is presented in Section 7.3.
7.2.5 Nonfunctional Requirements A nonfunctional requirement (NFR) can be described as a quality attribute, a perfor- mance attribute, a security attribute, or a general constraint on a system. These are often not easy for stakeholders to articulate. Chung [Chu09] suggests that there is a lopsided emphasis on functionality of the software, yet the software may not be use- ful or usable without the necessary nonfunctional characteristics.
It is possible to define a two-phase approach [Hne11] that can assist a software team and other stakeholders in identifying nonfunctional requirements. During the first phase, a set of software engineering guidelines is established for the system to be built. These include guidelines for best practice, but also address architectural style (Chapter 10) and the use of design patterns (Chapter 14). A list of NFRs (e.g., require- ments that address usability, testability, security, or maintainability) is then developed. A simple table lists NFRs as column labels and software engineering guidelines as row labels. A relationship matrix compares each guideline to all others, helping the team to assess whether each pair of guidelines is complementary, overlapping, con- flicting, or independent.
In the second phase, the team prioritizes each nonfunctional requirement by creat- ing a homogeneous set of nonfunctional requirements using a set of decision rules that establish which guidelines to implement and which to reject.
7.2.6 Traceability Traceability is a software engineering term that refers to documented links between software engineering work products (e.g., requirements and test cases). A traceability matrix allows a requirements engineer to represent the relationship between requirements and other software engineering work products. Rows of the traceability
110 PART TWO MODELING
matrix are labeled using requirement names, and columns can be labeled with the name of a software engineering work product (e.g., a design element or a test case). A matrix cell is marked to indicate the presence of a link between the two.
The traceability matrices can support a variety of engineering development activi- ties. They can provide continuity for developers as a project moves from one project phase to another, regardless of the process model being used. Traceability matrices often can be used to ensure the engineering work products have taken all requirements into account.
As the number of requirements and the number of work products grows, it becomes increasingly difficult to keep the traceability matrix up to date. Nonetheless, it is important to create some means for tracking the impact and evolution of the product requirements [Got11].
7 .3 Re Q u i R e m e n t s gat h e R i ng
Requirements gathering combines elements of problem solving, elaboration, negotia- tion, and specification. To encourage a collaborative, team-oriented approach to requirements gathering, stakeholders work together to identify the problem, propose elements of the solution, negotiate different approaches, and specify a preliminary set of solution requirements [Zah90].
7.3.1 Collaborative Requirements Gathering Many different approaches to collaborative requirements gathering have been pro- posed. Each makes use of a slightly different scenario, but all apply some variation on the following basic guidelines:
∙ Meetings (either real or virtual) are conducted and attended by both software engineers and other stakeholders.
∙ Rules for preparation and participation are established. ∙ An agenda is suggested that is formal enough to cover all important points
but informal enough to encourage the free flow of ideas. ∙ A “facilitator” (can be a customer, a developer, or an outsider) controls the
meeting. ∙ A “definition mechanism” (can be worksheets, flip charts, or wall stickers or
an electronic bulletin board, chat room, or virtual forum) is used.
The goal is to identify the problem, propose elements of the solution, negotiate different approaches, and specify a preliminary set of solution requirements.
A one- or two-page “product request” is generated during inception (Section 7.2). A meeting place, time, and date are selected; a facilitator is chosen; and attendees from the software team and other stakeholder organizations are invited to participate. If a system or product will serve many users, be absolutely certain that requirements are elicited from a representative cross section of users. If only one user defines all requirements, acceptance risk is high (meaning there may be several other stakehold- ers who will not accept the product). The product request is distributed to all attend- ees before the meeting date.
CHAPTER 7 UNDERSTANDING REQUIREMENTS 111
As an example, consider an excerpt from a product request written by a marketing person involved in the SafeHome project. This person writes the following narrative about the home security function that is to be part of SafeHome:
Our research indicates that the market for home management systems is growing at a rate of 40 percent per year. The first SafeHome function we bring to market should be the home security function. Most people are familiar with “alarm systems,” so this would be an easy sell. We might also consider using voice control of the system using some technology like Alexa.
The home security function would protect against and/or recognize a variety of unde- sirable “situations” such as illegal entry, fire, flooding, carbon monoxide levels, and others. It’ll use our wireless sensors to detect each situation, can be programmed by the homeowner, and will automatically contact a monitoring agency and the owner’s cell phone when a situation is detected.
In reality, others would contribute to this narrative during the requirements gather- ing meeting and considerably more information would be available. But even with additional information, ambiguity is present, omissions are likely to exist, and errors might occur. For now, the preceding “functional description” will suffice.
While reviewing the product request in the days before the meeting, each attendee is asked to make a list of objects that are part of the environment that surrounds the system, other objects that are to be produced by the system, and objects that are used by the system to perform its functions. In addition, each attendee is asked to make another list of services (processes or functions) that manipulate or interact with the objects. Finally, lists of constraints (e.g., cost, size, business rules) and performance criteria (e.g., speed, accuracy, security) are also developed. The attendees are informed that the lists are not expected to be exhaustive but are expected to reflect each person’s perception of the system.
Objects described for SafeHome might include the control panel, smoke detectors, window and door sensors, motion detectors, an alarm, an event (a sensor has been activated), a display, a tablet, telephone numbers, a telephone call, and so on. The list of services might include configuring the system, setting the alarm, monitoring the sensors, dialing the phone using a wireless router, programming the control panel, and reading the display (note that services act on objects). In a similar fashion, each attendee will develop lists of constraints (e.g., the system must recognize when sensors are not operating, must be user friendly, must interface directly to a standard phone line) and performance criteria (e.g., a sensor event should be recognized within 1 second, and an event priority scheme should be implemented).
The lists of objects can be pinned to the walls of the room using large sheets of paper, stuck to the walls using adhesive-backed sheets, or written on a wall board. Alternatively, the lists may have been posted on a group forum or at an internal web- site or posed in a social networking environment for review prior to the meeting. Ideally, each listed entry should be capable of being manipulated separately so that lists can be combined, entries can be deleted, and additions can be made. At this stage, critique and debate are strictly prohibited. Avoid the impulse to shoot down a cus- tomer’s idea as “too costly” or “impractical.” The idea here is to negotiate a list that is acceptable to all. To do this, you must keep an open mind.
After individual lists are presented in one topic area, the group creates a combined list by eliminating redundant entries, adding any new ideas that come up during the
112 PART TWO MODELING
discussion, but not deleting anything. After you create combined lists for all topic areas, discussion—coordinated by the facilitator—ensues. The combined list is short- ened, lengthened, or reworded to properly reflect the product or system to be devel- oped. The objective is to develop a consensus list of objects, services, constraints, and performance for the system to be built.
In many cases, an object or service described on a list will require further explana- tion. To accomplish this, stakeholders develop mini-specifications for entries on the lists or by creating a use case (Section 7.4) that involves the object or service. For example, the mini-spec for the SafeHome object Control Panel might be:
The control panel is a wall-mounted unit that is approximately 230 × 130 mm in size. The control panel has wireless connectivity to sensors and a tablet. User interaction occurs through a keypad containing 12 keys. A 75 × 75 mm OLED color display provides user feedback. Software provides interactive prompts, echo, and similar functions.
The mini-specs are presented to all stakeholders for discussion. Additions, dele- tions, and further elaboration are made. In some cases, the development of mini-specs will uncover new objects, services, constraints, or performance requirements that will be added to the original lists. During all discussions, the team may raise an issue that cannot be resolved during the meeting. An issues list is maintained so that these ideas will be acted on later.
Case Study Example Conducting a Requirements Gathering Meeting
The scene: A meeting room. The first requirements gathering meeting is in progress.
The players: Jamie Lazar, software team member; Vinod Raman, software team mem- ber; Ed Robbins, software team member; Doug Miller, software engineering manager; three members of marketing; a product engineering representative; and a facilitator.
The conversation: Facilitator (pointing at whiteboard): So that’s the current list of objects and services for the home security function.
Marketing person: That about covers it from our point of view.
Vinod: Didn’t someone mention that they wanted all SafeHome functionality to be ac- cessible via the Internet? That would include the home security function, no?
Marketing person: Yes, that’s right . . . we’ll have to add that functionality and the appropriate objects.
Facilitator: Does that also add some constraints?
Jamie: It does, both technical and legal.
Production rep: Meaning?
Jamie: We better make sure an outsider can’t hack into the system, disarm it, and rob the place or worse. Heavy liability on our part.
Doug: Very true.
Marketing: But we still need that . . . just be sure to stop an outsider from getting in.
Ed: That’s easier said than done and . . .
Facilitator (interrupting): I don’t want to de- bate this issue now. Let’s note it as an action item and proceed. (Doug, serving as the recorder for the meeting, makes an appropriate note.)
Facilitator: I have a feeling there’s still more to consider here. (The group spends the next 20 minutes refining and expanding the details of the home security function.)
safehome
CHAPTER 7 UNDERSTANDING REQUIREMENTS 113
Many stakeholder concerns (e.g., accuracy, data accessibility, security) are the basis for nonfunctional system requirements (Section 7.2). As stakeholders enunciate these concerns, software engineers must consider them within the context of the system to be built. The questions that must be answered [Lag10] are:
∙ Can we build the system? ∙ Will this development process allow us to beat our competitors to market? ∙ Do adequate resources exist to build and maintain the proposed system? ∙ Will the system performance meet the needs of our customers?
7.3.2 Usage Scenarios As requirements are gathered, an overall vision of system functions and features begin to materialize. However, it is difficult to move into more technical software engineer- ing activities until you understand how the features will be used by different classes of end users. To accomplish this, developers and users can create a set of scenarios that identify a thread of usage for the system to be constructed. The scenarios, often called use cases [Jac92], provide a description of how the system will be used. Use cases are discussed in greater detail in Section 7.4.
Developing a Preliminary User Scenario
The scene: A meeting room, continuing the first require-
ments gathering meeting.
The players: Jamie Lazar, software team member; Vinod Raman, software team mem- ber; Ed Robbins, software team member; Doug Miller, software engineering manager; three members of marketing; a product engineering representative; and a facilitator.
The conversation: Facilitator: We’ve been talking about security for access to SafeHome functionality that will be accessible via the Internet. I’d like to try something. Let’s develop a usage scenario for access to the home security function.
Jamie: How?
Facilitator: We can do it a couple of different ways, but for now, I’d like to keep things really informal. Tell us (he points at a marketing per- son) how you envision accessing the system.
Marketing person: Um . . . well, this is the kind of thing I’d do if I was away from home and I
had to let someone into the house, say a housekeeper or repair guy, who didn’t have the security code.
Facilitator (smiling): That’s the reason you’d do it . . . tell me how you’d actually do this.
Marketing person: Um . . . the first thing I’d need is a PC. I’d log on to a website we’d maintain for all users of SafeHome. I’d provide my user ID and . . .
Vinod (interrupting): The Web page would have to be secure, encrypted, to guarantee that we’re safe and . . .
Facilitator (interrupting): That’s good informa- tion, Vinod, but it’s technical. Let’s just focus on how the end user will use this capability. OK?
Vinod: No problem.
Marketing person: So as I was saying, I’d log on to a website and provide my user ID and two levels of passwords.
Jamie: What if I forget my password?
safehome
114 PART TWO MODELING
7.3.3 Elicitation Work Products The work products produced during requirements elicitation will vary depending on the size of the system or product to be built. For large systems, the work products may include: (1) a statement of need and feasibility; (2) a bounded statement of scope for the system or product; (3) a list of customers, users, and other stakeholders who participated in requirements elicitation; (4) a description of the system’s technical environment; (5) a list of requirements (preferably organized by function) and the domain constraints that apply to each; and (6) a set of usage scenarios that provide insight into the use of the system or product under different operating conditions. Each of these work products is reviewed by all people who have participated in require- ments elicitation.
7 .4 de v e L o p i ng us e ca s e s
A use case tells a stylized story about how an end user (playing one of several pos- sible roles) interacts with the system under a specific set of circumstances. The story may be narrative text (a user story), an outline of tasks or interactions, a template- based description, or a diagrammatic representation. Regardless of its form, a use case depicts the software or system from the end user’s point of view.
The first step in writing a use case is to define the set of “actors” that will be involved in the story. Actors are the different people (or devices) that use the system or product within the context of the function and behavior that is to be described. Actors will represent the roles that people (or devices) play as the system operates. Defined somewhat more formally, an actor is anything that communicates with the system or product and that is external to the system itself. Every actor has one or more goals when using the system.
It is important to note that an actor and an end user are not necessarily the same thing. A typical user may play several different roles when using a system, whereas an actor represents a class of external entities (often, but not always, people) that play just one role in the context of the use case. As an example, consider a user who interacts with the program that allows experimenting with alarm sensor configuration
Facilitator (interrupting): Good point, Jamie, but let’s not address that now. We’ll make a note of that and call it an exception. I’m sure there’ll be others.
Marketing person: After I enter the pass- words, a screen representing all SafeHome functions will appear. I’d select the home secu- rity function. The system might request that I verify who I am, say, by asking for my address or phone number or something. It would then display a picture of the security system control
panel along with a list of functions that I can perform—arm the system, disarm the system, disarm one or more sensors. I suppose it might also allow me to reconfigure security zones and other things like that, but I’m not sure. (As the marketing person continues talking, Doug takes copious notes; these form the basis for the first informal usage scenario. Alternatively, the marketing person could have been asked to write the scenario, but this would be done outside the meeting.)
CHAPTER 7 UNDERSTANDING REQUIREMENTS 115
in a virtual building. After careful review of requirements, the software for the control computer requires four different modes (roles) for interaction: placement mode, testing mode, monitoring mode, and troubleshooting mode. Therefore, four actors can be defined: editor, tester, monitor, and troubleshooter. In some cases, the user can play all the roles. In others, different people may play the role of each actor.
Because requirements elicitation is an evolutionary activity, not all actors are iden- tified during the first iteration. It is possible to identify primary actors [Jac92] during the first iteration and secondary actors as more is learned about the system. Primary actors interact to achieve required system function and derive the intended benefit from the system. They work directly and frequently with the software. Secondary actors support the system so that primary actors can do their work.
Once actors have been identified, use cases can be developed. Jacobson [Jac92] suggests questions that should be answered by a use case:
1. Who is the primary actor, the secondary actor(s)? 2. What are the actor’s goals? 3. What preconditions should exist before the story begins? 4. What main tasks or functions are performed by the actor? 5. What exceptions might be considered as the story is described? 6. What variations in the actor’s interaction are possible? 7. What system information will the actor acquire, produce, or change? 8. Will the actor have to inform the system about changes in the external
environment? 9. What information does the actor desire from the system? 10. Does the actor wish to be informed about unexpected changes?
Recalling basic SafeHome requirements, we define four actors: homeowner (a user), setup manager (likely the same person as homeowner, but playing a different role), sensors (devices attached to the system), and the monitoring and response subsystem (the central station that monitors the SafeHome home security function). For the purposes of this example, we consider only the homeowner actor. The home- owner actor interacts with the home security function in different ways using either the alarm control panel, a tablet, or a cell phone.
The homeowner:
1. Enters a password to allow all other interactions 2. Inquires about the status of a security zone 3. Inquires about the status of a sensor 4. Presses the panic button in an emergency 5. Activates and deactivates the security system
Considering the situation in which the homeowner uses the control panel, the basic use case for system activation follows:
1. The homeowner observes the SafeHome control panel (Figure 7.1) to deter- mine if the system is ready for input. If the system is not ready, a not ready
116 PART TWO MODELING
message is displayed on the LCD display, and the homeowner must physically close windows or doors so that the not ready message disappears. (A not ready message implies that a sensor is open, i.e., that a door or window is open.)
2. The homeowner uses the keypad to key in a four-digit password. The password is compared with the valid password stored in the system. If the password is incorrect, the control panel will beep once and reset itself for additional input. If the password is correct, the control panel awaits further action.
3. The homeowner selects and keys in “stay” or “away” (see Figure 7.1) to acti- vate the system. Stay activates only perimeter sensors (inside motion detecting sensors are deactivated). Away activates all sensors.
4. When activation occurs, a red alarm light can be observed by the homeowner.
The basic use case presents a high-level user story that describes the interaction between the actor and the system.
In many instances, uses cases are further elaborated to provide considerably more detail about the interaction. For example, Cockburn [Coc01b] suggests the following template for detailed descriptions of use cases:
Use case: InitiateMonitoring
Primary actor: Homeowner. Goal in context: To set the system to monitor sensors when the
homeowner leaves the house or remains inside. Preconditions: System has been programmed for a password and to
recognize various sensors. Trigger: The homeowner decides to “set” the system, that is,
to turn on the alarm functions.
o� away stay
max test bypass
instant code chime
ready
panic
SafeHome
alarm check
fire
away stay
instant bypass
not ready
1
armed power
2 3
4 5 6
7 8 9
* 0 #
Figure 7.1 SafeHome control panel
CHAPTER 7 UNDERSTANDING REQUIREMENTS 117
Scenario: 1. Homeowner observes control panel. 2. Homeowner enters password. 3. Homeowner selects “stay” or “away.” 4. Homeowner observes red alarm light to indicate that SafeHome has
been armed.
Exceptions: 1. Control panel is not ready: Homeowner checks all sensors to determine which
are open and then closes them. 2. Password is incorrect (control panel beeps once): Homeowner reenters correct
password. 3. Password not recognized: Monitoring and response subsystem must be contacted
to reprogram password. 4. Stay is selected: Control panel beeps twice, and a stay light is lit; perimeter
sensors are activated. 5. Away is selected: Control panel beeps three times, and an away light is lit; all
sensors are activated.
Priority: Essential, must be implemented When available: First increment Frequency of use: Many times per day Channel to actor: Via control panel interface Secondary actors: Support technician, sensors Channels to secondary actors:
Support technician: phone line Sensors: hardwired and radio frequency interfaces
Open issues: 1. Should there be a way to activate the system without the use of a password or
with an abbreviated password? 2. Should the control panel display additional text messages? 3. How much time does the homeowner have to enter the password from the time
the first key is pressed? 4. Is there a way to deactivate the system before it actually activates?
Use cases for other homeowner interactions would be developed in a similar manner. It is important to review each use case with care. If some element of the interaction is ambiguous, it is likely that a review of the use case will indicate a problem. Use cases are often written informally as user stories. However, using the template shown here helps to ensure that you’ve addressed all key issues. This is very important for systems where user safety or security is a stakeholder concern.
118 PART TWO MODELING
7 .5 bu i L d i ng t h e ana Lys i s mo d e L
The intent of the analysis model is to provide a description of the required informa- tional, functional, and behavioral domains for a computer-based system. The model changes dynamically as you learn more about the system to be built, and as stakehold- ers understand more about what they really require. For that reason, the analysis model is a snapshot of requirements at any given time. You should expect it to change.
As the analysis model evolves, certain elements will become relatively stable, pro- viding a solid foundation for the design tasks that follow. However, other elements of the model may be more volatile, indicating that stakeholders do not yet fully under- stand requirements for the system. If your team finds that it does not use certain elements of the analysis model as the project moves to design and construction, those elements should not be created in the future and should not be maintained as the requirements change in the current project. The analysis model and the methods that are used to build it are presented in detail in Chapter 8. We present a brief overview in the sections that follow.
Developing a High-Level Use Case Diagram
The scene: A meeting room, continuing the requirements
gathering meeting.
The players: Jamie Lazar, software team member; Vinod Raman, software team mem- ber; Ed Robbins, software team member; Doug Miller, software engineering manager; three members of marketing; a product engineering representative; and a facilitator.
The conversation: Facilitator: We’ve spent a fair amount of time talking about SafeHome home security func- tionality. During the break I sketched a use case diagram to summarize the important sce- narios that are part of this function. Take a look.
(All attendees look at Figure 7.2.)
Jamie: I’m just beginning to learn UML nota- tion. So the home security function is repre- sented by the big box with the ovals inside it? And the ovals represent use cases that we’ve written in text?
Facilitator: Yep. And the stick figures repre- sent actors—the people or things that interact
with the system as described by the use case . . . oh, I use the labeled square to repre- sent an actor that’s not a person . . . in this case, sensors. Doug: Is that legal in UML? Facilitator: Legality isn’t the issue. The point is to communicate information. I view the use of a humanlike stick figure for repre- senting a device to be misleading. So I’ve adapted things a bit. I don’t think it creates a problem. Vinod: Okay, so we have use case narratives for each of the ovals. Do we need to develop the more detailed template-based narratives I’ve read about? Facilitator: Probably, but that can wait until we’ve considered other SafeHome functions. Marketing person: Wait, I’ve been looking at this diagram and all of a sudden I realize we missed something. Facilitator: Oh really. Tell me what we’ve missed.
(The meeting continues.)
safehome
CHAPTER 7 UNDERSTANDING REQUIREMENTS 119
7.5.1 Elements of the Analysis Model There are many ways to look at the requirements for a computer-based system. Some software people argue that it’s best to select one mode of representation (e.g., the use case) and apply it to the exclusion of all other modes. Other practitioners believe that it’s worthwhile to use several different modes of representation to depict the analysis model. Using different modes of representation forces you to consider requirements from different viewpoints—an approach that has a higher probability of uncovering omissions, inconsistencies, and ambiguity. It is always a good idea to get stakeholders involved. One of the best ways to do this is to have each stakeholder write use cases that describe how the software will be used. A set of generic elements common to most analysis models is introduced in this chapter.
Scenario-Based Elements. Scenario-based elements of the requirements model are often the first part of the model that is developed. They describe the system from the user’s point of view. For example, basic user stories (Section 7.4) and their corre- sponding use case diagrams (Figure 7.2) may evolve into more elaborate template- based use cases (Section 7.4). As such, they serve as input for the creation of other modeling elements. It is always a good idea to get stakeholders involved. One of the best ways to do this is to have each stakeholder write use cases that describe how the software will be used.
Homeowner
System Administrator
Arms/disarms system
Accesses system
via Internet
Responds to alarm events
Encounters an error condition
Reconfigures sensors and
related system features
Sensors
Figure 7.2 UML use case diagram for SafeHome home security function
120 PART TWO MODELING
Class-Based Elements. Each usage scenario implies a set of objects that are mani- pulated as an actor interacts with the system. These objects are categorized into classes—a collection of things that have similar attributes and common behaviors. For example, a UML class diagram can be used to depict a Sensor class for the SafeHome security function (Figure 7.3).
Note that the diagram lists the attributes of sensors (e.g., name, type) and the operations (e.g., identify, enable) that can be applied to modify these attributes. Other analysis modeling elements depict how classes collaborate with one another and the relationships and interactions among classes. One way to isolate classes is to look for descriptive nouns in a use case script. At least some of the nouns will be candi- date classes. The verbs found in the use case script may be considered candidate methods for these classes. These and other techniques are discussed in more detail in Chapter 8.
Behavioral Elements. The behavior of a computer-based system can have a pro- found effect on the design that is chosen and the implementation approach that is applied. Therefore, the requirements model must provide modeling elements that depict behavior.
The state diagram is one method for representing the behavior of a system by depicting its states and the events that cause the system to change state. A state is any externally observable mode of behavior. In addition, the state diagram indicates what actions (e.g., process activations) are taken when events occur. External stimuli (events) cause transitions between states.
Name Type Location Area Characteristics
Identify() Enable() Disable() Reconfigure()
Sensor Figure 7.3
Class diagram for sensor
CHAPTER 7 UNDERSTANDING REQUIREMENTS 121
To illustrate the use of a state diagram, consider software embedded within the SafeHome control panel that is responsible for reading user input. An example of UML state diagram notation is shown in Figure 7.4. Further discussion of behavioral modeling is presented in Chapter 8.
System Status = "ready" Display msg = "enter cmd" Display status = "steady"
Entry/subsystems ready Do: poll user input panel Do: ready user input Do: interpret user input
Reading Commands
System Status = "o�"
cmd = o�
Screen Blank
Figure 7.4 UML state diagram notation
Preliminary Behavioral Modeling
The scene: A meeting room, continuing the requirements meeting.
The players: Jamie Lazar, software team member; Vinod Raman, software team mem- ber; Ed Robbins, software team member; Doug Miller, software engineering manager; three members of marketing; a product engineering representative; and a facilitator.
The conversation: Facilitator: We’ve just about finished talking about SafeHome home security functionality. But before we do, I want to discuss the behav- ior of the function.
Marketing person: I don’t understand what you mean by behavior.
Ed (smiling): That’s when you give the prod- uct a “timeout” if it misbehaves.
Facilitator: Not exactly. Let me explain.
(The facilitator explains the basics of behav- ioral modeling to the requirements gathering team.)
Marketing person: This seems a little techni- cal. I’m not sure I can help here.
Facilitator: Sure you can. What behavior do you observe from the user’s point of view?
Marketing person: Uh . . . well, the system will be monitoring the sensors. It’ll be reading commands from the homeowner. It’ll be displaying its status.
Facilitator: See, you can do it.
Jamie: It’ll also be polling the PC to determine if there is any input from it, for example, Internet- based access or configuration information.
Vinod: Yeah, in fact, configuring the system is a state in its own right.
Doug: You guys are rolling. Let’s give this a bit more thought . . . is there a way to diagram this stuff?
Facilitator: There is, but let’s postpone that until after the meeting.
safehome
122 PART TWO MODELING
7.5.2 Analysis Patterns Anyone who has done requirements engineering on more than a few software projects notices that certain problems reoccur across all projects within a specific application domain. These analysis patterns [Fow97] suggest solutions (e.g., a class, a function, a behavior) within the application domain that can be reused when modeling many applications.
Analysis patterns are integrated into the analysis model by reference to the pattern name. They are also stored in a repository so that requirements engineers can use search facilities to find and reuse them. Information about an analysis pattern (and other types of patterns) is presented in a standard template [Gey01] that is discussed in more detail in Chapter 14. Examples of analysis patterns and further discussion of this topic are presented in Chapter 8.
7 .6 ne g ot i at i ng Re Q u i R e m e n t s
In an ideal world, the requirements engineering tasks (inception, elicitation, and elab- oration) determine customer requirements in sufficient detail to proceed to subsequent software engineering activities. Unfortunately, this rarely happens. You may have to enter into negotiations with one or more stakeholders. In most cases, stakeholders are asked to balance functionality, performance, and other product or system characteristics against cost and time to market. The intent of these negotiations is to develop a project plan that meets stakeholder needs while at the same time reflecting the real-world constraints (e.g., time, people, budget) that have been placed on the software team.
The best negotiations strive for a “win-win” result. That is, stakeholders win by getting the system or product that satisfies most their needs, and you (as a member of the software team) win by working to realistic and achievable budgets and deadlines.
Fricker [Fri10] and his colleagues suggest replacing the traditional handoff of requirements specifications to software teams with a bidirectional communication pro- cess called handshaking. Handshaking might be one way to accomplish a win-win result. In handshaking, the software team proposes solutions to requirements, describes their impact, and communicates their intentions to customer representatives. The cus- tomer representatives review the proposed solutions, focusing on missing features and seeking clarification of novel requirements. Requirements are determined to be good enough if the customers accept the proposed solution. Handshaking tends to improve identification, analysis, and selection of variants and promotes win-win negotiation.
The Start of a Negotiation
The scene: Lisa Perez’s office, after the first requirements
gathering meeting.
The players: Doug Miller, software engineer- ing manager, and Lisa Perez, marketing manager.
The conversation: Lisa: So, I hear the first meeting went really well.
Doug: Actually, it did. You sent some good people to the meeting . . . they really contributed.
safehome
CHAPTER 7 UNDERSTANDING REQUIREMENTS 123
7 .7 Re Q u i R e m e n t s mo n i to R i ng
Incremental development is commonplace. This means that use cases evolve, new test cases are developed for each new software increment, and continuous integration of source code occurs throughout a project. Requirements monitoring can be extremely useful when incremental development is used. It encompasses five tasks: (1) distrib- uted debugging uncovers errors and determines their cause, (2) run-time verification determines whether software matches its specification, (3) run-time validation assesses whether the evolving software meets user goals, (4) business activity monitoring eval- uates whether a system satisfies business goals, and (5) evolution and codesign pro- vides information to stakeholders as the system evolves.
Incremental development implies the need for incremental validation. Requirements monitoring supports continuous validation by analyzing user goal models against the system in use. For example, a monitoring system might continuously assess user satisfaction and use feedback to guide incremental improvements [Rob10].
7 .8 va L i dat i ng Re Q u i R e m e n t s
As each element of the requirements model is created, it is examined for inconsistency, omissions, and ambiguity. This is true even for agile process models where require- ments tend to be written as user stories and/or test cases. The requirements represented
Lisa (smiling): Yeah, they actually told me they got into it, and it wasn’t a “propeller head activity.”
Doug (laughing): I’ll be sure to take off my te- chie beanie the next time I visit . . . Look, Lisa, I think we may have a problem with getting all of the functionality for the home security sys- tem out by the dates your management is talk- ing about. It’s early, I know, but I’ve already been doing a little back-of-the-envelope planning and . . .
Lisa (frowning): We’ve got to have it by that date, Doug. What functionality are you talking about?
Doug: I figure we can get full home security functionality out by the drop-dead date, but we’ll have to delay Internet access ‘til the second release.
Lisa: Doug, it’s the Internet access that gives SafeHome “gee whiz” appeal. We’re going to
build our entire marketing campaign around it. We’ve gotta have it!
Doug: I understand your situation, I really do. The problem is that in order to give you Inter- net access, we’ll have to have a fully secure website up and running. That takes time and people. We’ll also have to build a lot of addi- tional functionality into the first release . . . I don’t think we can do it with the resources we’ve got.
Lisa (still frowning): I see, but you’ve got to figure out a way to get it done. It’s pivotal to home security functions and to other functions as well . . . those can wait until the next releases . . . I’ll agree to that.
Lisa and Doug appear to be at an impasse, and yet they must negotiate a solution to this problem. Can they both “win” here? Playing the role of a mediator, what would you suggest?
124 PART TWO MODELING
by the model are prioritized by stakeholders and grouped within requirements packages that will be implemented as software increments. A review of the requirements model addresses the following questions:
1. Is each requirement consistent with the overall objectives for the system or product?
2. Have all requirements been specified at the proper level of abstraction? That is, do some requirements provide a level of technical detail that is inappropri- ate at this stage?
3. Is the requirement really necessary or does it represent an add-on feature that may not be essential to the objective of the system?
4. Is each requirement bounded and unambiguous? 5. Does each requirement have attribution? That is, is a source (generally, a
specific individual) noted for each requirement? 6. Do any requirements conflict with other requirements? 7. Is each requirement achievable in the technical environment that will house
the system or product? 8. Is each requirement testable, once implemented? 9. Does the requirements model properly reflect the information, function, and
behavior of the system to be built? 10. Has the requirements model been “partitioned” in a way that exposes progres-
sively more detailed information about the system? 11. Have requirements patterns been used to simplify the requirements model?
Have all patterns been properly validated? Are all patterns consistent with customer requirements?
These and other questions should be asked and answered to ensure that the require- ments model is an accurate reflection of stakeholder needs and that it provides a solid foundation for design.
7 .9 su m m a Ry
Requirements engineering tasks are conducted to establish a solid foundation for design and construction. Requirements engineering occurs during the communication and modeling activities that have been defined for the generic software process. Seven requirements engineering activities—inception, elicitation, elaboration, negotiation, specification, validation, and management—are conducted by members of the soft- ware team and product stakeholders.
At project inception, stakeholders establish basic problem requirements, define overriding project constraints, and address major features and functions that must be present for the system to meet its objectives. This information is refined and expanded during elicitation—a requirements gathering activity that makes use of facilitated meetings and the development of usage scenarios (user stories).
Elaboration further expands requirements in a model—a collection of scenario- based, activity-based, class-based, and behavioral elements. The model may reference
CHAPTER 7 UNDERSTANDING REQUIREMENTS 125
analysis patterns, characteristics of the problem domain that have been seen to reoccur across different applications.
As requirements are identified and the requirements model is being created, the software team and other project stakeholders negotiate the priority, availability, and relative cost of each requirement. The intent of this negotiation is to develop a real- istic project plan. Each requirement needs to be validated against customer needs to ensure that the right system is to be built.
Pro b l e m s a n d Po i n t s to Po n d e r
7.1. Why is it that many software developers don’t pay enough attention to requirements engi- neering? Are there ever circumstances where you can skip it?
7.2. You have been given the responsibility to elicit requirements from a customer who tells you he is too busy to meet with you. What should you do?
7.3. Discuss some of the problems that occur when requirements must be elicited from three or four different customers.
7.4. Your instructor will divide the class into groups of four or six students. Half of the group will play the role of the marketing department and half will take on the role of software engi- neering. Your job is to define requirements for the SafeHome security function described in this chapter. Conduct a requirements gathering meeting using the guidelines presented in this chapter.
7.5. Develop a complete use case for one of the following activities:
a. Making a withdrawal at an ATM b. Using your charge card for a meal at a restaurant c. Searching for books (on a specific topic) using an online bookstore
7.6. Write a user story for one of the activities listed in Problem 7.5.
7.7. Consider the use case you created in Problem 7.5, and write a nonfunctional requirement for the application.
7.8. Using the template presented in Section 7.5.2, suggest one or more analysis patterns for the following application domains:
a. E-mail software. b. Internet browsers. c. Mobile app creation software.
7.9. What does win-win mean in the context of negotiation during the requirements engineer- ing activity?
7.10. What do you think happens when requirement validation uncovers an error? Who is involved in correcting the error?
Design element: Quick Look icon magnifying glass: © Roger Pressman
126
What is it? Requirements modeling uses a com- bination of text and diagrammatic forms to de- pict requirements in a way that is relatively easy to understand, and more important, straightforward to review for correctness, completeness, and consistency.
Who does it? A software engineer (sometimes called an analyst) builds these models from re- quirements elicited from various stakeholders.
Why is it important? Requirements models can be readily evaluated by all stakeholders, resulting in useful feedback at the earliest possible time. Later, as the model is refined, it becomes the basis for software design.
What are the steps? Requirements modeling combines three steps: scenario-based model- ing, class modeling, and behavioral modeling.
What is the work product? Usage scenarios, called use cases, describe software functions and usage. In addition, a series of UML dia- grams can be used to represent system be- havior and other aspects.
How do I ensure that I’ve done it right? Re- quirements modeling work products must be reviewed for correctness, completeness, and consistency.
Q u i c k L o o k
activity diagram . . . . . . . . . . . . . . . . . . . . . . . . 146 analysis classes . . . . . . . . . . . . . . . . . . . . . . . . 137 attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 behavioral model . . . . . . . . . . . . . . . . . . . . . . 149 class-based modeling . . . . . . . . . . . . . . . . . . . 127 collaborations . . . . . . . . . . . . . . . . . . . . . . . . . 144 CRC modeling . . . . . . . . . . . . . . . . . . . . . . . . . 144 events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 formal use case . . . . . . . . . . . . . . . . . . . . . . . . 135 functional model . . . . . . . . . . . . . . . . . . . . . . . 146 grammatical parse . . . . . . . . . . . . . . . . . . . . . 137 operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
procedural view . . . . . . . . . . . . . . . . . . . . . . . . 146 requirements analysis . . . . . . . . . . . . . . . . . . . 127 requirements modeling . . . . . . . . . . . . . . . . . 129 responsibilities . . . . . . . . . . . . . . . . . . . . . . . . 144 scenario-based modeling . . . . . . . . . . . . . . . . 128 sequence diagrams . . . . . . . . . . . . . . . . . . . . . 148 state diagrams . . . . . . . . . . . . . . . . . . . . . . . . . 150 swimlane diagram . . . . . . . . . . . . . . . . . . . . . . 151 UML models . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
documentation . . . . . . . . . . . . . . . . . . . . . . 135 exception . . . . . . . . . . . . . . . . . . . . . . . . . . 134
k e y c o n c e p t s
C H A P T E R
8 The written word is a wonderful vehicle for communication, but it is not neces- sarily the best way to represent the requirements for computer software. At a technical level, software engineering begins with a series of modeling tasks that lead to a specification of requirements and a design representation for the soft- ware to be built. The requirements model is actually a set of models that make up the first technical representation of a system. Software engineers often prefer to include graphical representations of complex model relationships.
Requirements Modeling— A Recommended Approach
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 127
For some types of software, a user story (Section 7.3.2) may be the only require- ments modeling representation that is required. For others, formal use cases (Section 7.4) and class-based models (Section 8.3) may be developed. Class-based modeling represents the objects that the system will manipulate, the operations (also called methods or services) that will be applied to the objects to effect the manipu- lation, relationships (some hierarchical) between the objects, and the collaborations that occur between the classes that are defined. Class-based methods can be used to create a representation of an application that can be understood by nontechnical stakeholders.
In still other situations, complex application requirements may demand an examina- tion of how an application behaves in reaction to either internal or external events. These behaviors need to be modeled (Section 8.5) as well. UML diagrams have become a standard software engineering means of modeling analysis model element relationships and behaviors graphically. As the requirements model is refined and expanding, it evolves into a specification that can be used by software engineers in the creation of the software design.
The important thing to keep in mind when modeling requirements is to only create the models that will be used by the development team. If models developed early in a requirements analysis phase of a project are not referred to during the design and implementation phases, they may not be worth updating. The sections that follow present a series of informal guidelines that will assist in the creation and representa- tion of requirements models.
8 .1 Re Q u i R e m e n t s AnA Lys i s
Requirements analysis results in the specification of software’s operational character- istics, indicates software’s interface with other system elements, and establishes con- straints that software must meet. Requirements analysis allows you (regardless of whether you’re called a software engineer, an analyst, or a modeler) to elaborate on basic requirements established during the inception, elicitation, and negotiation tasks that are part of requirements engineering (Chapter 7).
The requirements modeling action results in one or more of the following types of models:
∙ Scenario-based models of requirements from the point of view of various system “actors.”
∙ Class-oriented models that represent object-oriented classes (attributes and operations) and how classes collaborate to achieve system requirements.
∙ Behavioral models that depict how the software reacts to internal or external “events.”
∙ Data models that depict the information domain for the problem. ∙ Flow-oriented models that represent the functional elements of the system and
how they transform data as they move through the system.
These models provide a software designer with information that can be translated to architectural-, interface-, and component-level designs. Finally, the requirements
128 PART TWO MODELING
model (and the software requirements specification) provides the developer and the customer with the means to assess quality once software is built.
In this section, we focus on scenario-based modeling—a technique that is very popular throughout the software engineering community. In Sections 8.3 and 8.5 we consider class-based modeling and behavioral modeling. Over the past decade, flow and data modeling have become less commonly used, while scenario and class-based methods, supplemented with behavioral approaches have grown in popularity.1
8.1.1 Overall Objectives and Philosophy Throughout analysis modeling, your primary focus is on what, not how. What user interaction occurs, what objects does the system manipulate, what functions must the system perform, what behaviors does the system exhibit, what interfaces are defined, and what constraints apply?2
In previous chapters, we noted that complete specification of requirements may not be possible at this stage. The customer may be unsure of precisely what is required for certain aspects of the system. The developer may be unsure that a specific approach will properly accomplish function and performance. These realities mitigate in favor of an iterative approach to requirements analysis and modeling. The analyst should model what is known and use that model as the basis for design of the software increment.3
The requirements model must achieve three primary objectives: (1) to describe what the customer requires, (2) to establish a basis for the creation of a software design, and (3) to define a set of requirements that can be validated once the software is built. The analysis model bridges the gap between a system-level description that describes overall system or business functionality (software, hardware, data, human elements) and a software design (Chapters 9 through 14) that describes the software’s application architecture, user interface, and component-level structure. This relation- ship is illustrated in Figure 8.1.
It is important to note that all elements of the requirements model will be directly traceable to parts of the design model. A clear division between analysis and design modeling tasks is not always possible. Some design invariably occurs as part of anal- ysis, and some analysis will be conducted during design.
8.1.2 Analysis Rules of Thumb Several rules of thumb [Arl02] are worth considering when creating an analysis model. First, focus on the problem or business domain while keeping the level of abstraction high. Second, recognize that an analysis model should provide insight into
1 A presentation of flow-oriented modeling and data modeling is no longer included in this chapter. However, copious information about these older requirements modeling methods can be found on the Web. If you have interest, use the search phrase “structured analysis.”
2 It should be noted that as customers become more technologically sophisticated, there is a trend toward the specification of how as well as what. However, the primary focus should remain on what.
3 Alternatively, the software team may choose to create a prototype (Chapter 4) to better understand requirements for the system.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 129
the information domain, the function, and the behavior of the software. Third, delay a consideration of software architecture and nonfunctional details until later in the modeling activity. Also, it’s important to be aware of the ways in which elements of the software are interconnnected with other elements (we call this system coupling).
The analysis model must be structured in a way that provides value to all stake- holders and should be kept as simple as possible without sacrificing clarity.
8.1.3 Requirements Modeling Principles Over the past four decades, several requirements modeling methods have been devel- oped. Investigators have identified requirements analysis problems and their causes and have developed a variety of modeling notations and corresponding sets of heu- ristics to overcome them. Each analysis method has a unique point of view. A set of operational principles relates analysis methods:
Principle 1. The information domain of a problem must be represented and understood. The information domain encompasses the data that flow into the sys- tem (from end users, other systems, or external devices), the data that flow out of the system (via the user interface, network interfaces, reports, graphics, and other means), and the data stores that collect and organize the data that are maintained permanently.
Principle 2. The functions that the software performs must be defined. Soft- ware functions provide direct benefit to end users and those that provide internal support for those features that are user visible. Some functions transform data that
ign Model Desi M d
ysisy Moddel
Analyy
System Descriptioniption
Figure 8.1 The analysis model as a bridge between the system description and the design model
130 PART TWO MODELING
flow into the system. In other cases, functions effect some level of control over internal software processing or external system elements.
Principle 3. The behavior of the software (as a consequence of external events) must be represented. The behavior of computer software is driven by its interaction with the external environment. Input provided by end users, control data provided by an external system, or monitoring data collected over a network all cause the software to behave in a specific way.
Principle 4. The models that depict information, function, and behavior must be partitioned in a manner that uncovers detail in a layered (or hierarchical) fashion. Requirements modeling is the first step in software engineering problem solving. It allows you to better understand the problem and establishes a basis for the solution (design). Complex problems are difficult to solve in their entirety. For this reason, you should use a divide-and-conquer strategy. A large, complex prob- lem is divided into subproblems until each subproblem is relatively easy to under- stand. This concept is called partitioning or separation of concerns, and it is a key strategy in requirements modeling.
Principle 5. The analysis task should move from essential information toward implementation detail. Analysis modeling begins by describing the problem from the end-user’s perspective. The “essence” of the problem is described without any consideration of how a solution will be implemented. For example, a video game requires that the player “instruct” its protagonist on what direction to proceed as she moves into a dangerous maze. That is the essence of the problem. Implemen- tation detail (normally described as part of the design model) indicates how the essence will be implemented. For the video game, voice input might be used. Alter- natively, a keyboard command might be typed, a game pad joystick (or mouse) might be pointed in a specific direction, a motion-sensitive device might be waved in the air, or a device that reads the player’s body or eye movements directly can be used.
By applying these principles, a software engineer approaches a problem system- atically. But how are these principles applied in practice? This question will be answered in the remainder of this chapter.
8 .2 sc e nA R i o-BA s e d mo d e L i ng
Although the success of a computer-based system or product is measured in many ways, user satisfaction resides at the top of the list. If you understand how end users (and other actors) want to interact with a system, your software team will be better able to properly characterize requirements and build meaningful analysis and design models. Using UML4 to model requirements begins with the creation of scenarios in the form of use case diagrams, activity diagrams, and sequence diagrams.
4 UML will be used as the modeling notation throughout this book. Appendix 1 provides a brief tutorial for those readers who may be unfamiliar with basic UML notation.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 131
8.2.1 Actors and User Profiles A UML actor models an entity that interacts with a system object. Actors may rep- resent roles played by human stakeholders or external hardware as they interact with system objects by exchanging information. A single physical entity may be portrayed by several actors if the physical entity takes on several roles that are relevant to real- izing different system functions.
A UML profile provides a way of extending an existing model to other domains or platforms. This might allow you to revise the model of a Web-based system and model the system for various mobile platforms. Profiles might also be used to model the system from the viewpoints of different users. For example, system administrators may have a different view of the functionality of an automated teller machine than end users.
8.2.2 Creating Use Cases In Chapter 7, we discussed user stories as a way of summarizing the stakeholders’ perspective on how they will interact with the proposed system. However, they are written in plain English or the language used by the stakeholders. Developers need more precise means of describing this interaction before beginning to create the soft- ware. Alistair Cockburn characterizes a use case as a “contract for behavior” [Coc01b]. As we discussed in Chapter 7, the “contract” defines the way in which an actor5 uses a computer-based system to accomplish some goal. In other words, a use case captures the interactions that occur between producers and consumers of information within the system itself. In this section, we examine how preliminary use cases are developed as part of the analysis modeling activity.6
In Chapter 7, we noted that a use case describes a specific usage scenario in straightforward language from the point of view of a defined actor. But how do you know (1) what to write about, (2) how much to write about it, (3) how detailed to make your description, and (4) how to organize the description? These are the ques- tions that must be answered if use cases are to provide value as a modeling tool.
What to Write About? The first two requirements engineering tasks—inception and elicitation—provide you with the information you’ll need to begin writing use cases. Requirements gathering meetings and other requirements engineering mecha- nisms are used to identify stakeholders, define the scope of the problem, specify overall operational goals, establish priorities, outline all known functional require- ments, and describe the things (objects) that will be manipulated by the system.
To begin developing a set of use cases, list the functions or activities performed by a specific actor. You can obtain these from a list of required system functions, through conversations with stakeholders, or by an evaluation of activity diagrams (Section 8.4) developed as part of requirements modeling.
5 An actor is not a specific person, but rather a role that a person (or a device) plays within a specific context. An actor “calls on the system to deliver one of its services” [Coc01b].
6 Use cases are a particularly important part of analysis modeling for user interfaces. Interface analysis and design is discussed in detail in Chapter 12.
132 PART TWO MODELING
The SafeHome home surveillance function (subsystem) discussed in the sidebar identifies the following functions (an abbreviated list) that are performed by the home- owner actor:
∙ Select camera to view. ∙ Request thumbnails from all cameras. ∙ Display camera views in a device window. ∙ Control pan and zoom for a specific camera.
Developing Another Preliminary Use Case
The scene: A meeting room, during the second requirements
gathering meeting.
The players: Jamie Lazar, software team member; Ed Robbins, software team member; Doug Miller, software engineering manager; three members of marketing; a product engi- neering representative; and a facilitator.
The conversation: Facilitator: It’s time that we begin talking about the SafeHome surveillance function. Let’s develop a user scenario for access to the surveillance function.
Jamie: Who plays the role of the actor on this?
Facilitator: I think Meredith (a marketing per- son) has been working on that functionality. Why don’t you play the role?
Meredith: You want to do it the same way we did it last time, right?
Facilitator: Right . . . same way.
Meredith: Well, obviously the reason for sur- veillance is to allow the homeowner to check out the house while he or she is away, to re- cord and play back video that is captured . . . that sort of thing.
Ed: Will we use compression to store the video?
Facilitator: Good question, Ed, but let’s post- pone implementation issues for now. Meredith?
Meredith: Okay, so basically there are two parts to the surveillance function . . . the first
configures the system including laying out a floor plan—we need to have the AR/VR tools to help the homeowner do this—and the second part is the actual surveillance function itself. Since the layout is part of the configuration activity, I’ll focus on the surveillance function.
Facilitator (smiling): Took the words right out of my mouth.
Meredith: Um . . . I want to gain access to the surveillance function either via a mobile device or via the Internet. My feeling is that the Inter- net access would be more frequently used. Anyway, I want to be able to display camera views on a mobile device or PC and control pan and zoom for a specific camera. I specify the camera by selecting it from the house floor plan. I want to selectively record camera out- put and replay camera output. I also want to be able to block access to one or more cam- eras with a specific password. I also want the option of seeing small windows that show views from all cameras and then be able to pick the one I want enlarged.
Jamie: Those are called thumbnail views.
Meredith: Okay, then I want thumbnail views of all the cameras. I also want the interface for the surveillance function to have the same look and feel as all other SafeHome interfaces. I want it to be intuitive, meaning I don’t want to have to read a manual to use it.
Facilitator: Good job. Now, let’s go into this function in a bit more detail . . .
sAfeHome
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 133
∙ Selectively record camera output. ∙ Replay camera output. ∙ Access camera surveillance via the Internet.
As further conversations with the stakeholder (who plays the role of a homeowner) progress, the requirements gathering team develops use cases for each of the functions noted. In general, use cases are written first in an informal narrative fashion. If more formality is required, the same use case is rewritten using a structured format like the one proposed in Chapter 7.
To illustrate, consider the function access camera surveillance via the Internet— display camera views (ACS-DCV). The stakeholder who takes on the role of the homeowner actor might write the following user story:
Use case: Access camera surveillance via the Internet—display camera views (ACS-DCV)
Actor: homeowner
If I’m at a remote location, I can use any mobile device with appropriate browser soft- ware to log on to the SafeHome Products website. I enter my user ID and two levels of passwords and once I’m validated, I have access to all functionality for my installed SafeHome system. To access a specific camera view, I select “surveillance” from the major function buttons displayed. I then select “pick a camera” and the floor plan of the house is displayed. I then select the camera that I’m interested in. Alternatively, I can look at thumbnail snapshots from all cameras simultaneously by selecting “all cameras” as my viewing choice. Once I choose a camera, I select “view” and a one-frame-per- second view appears in a viewing window that is identified by the camera ID. If I want to switch cameras, I select “pick a camera,” the original viewing window disappears, and the floor plan of the house is displayed again. I then select the camera that I’m interested in. A new viewing window appears. A variation of a narrative use case presents the interaction as an ordered sequence
of user actions. Each action is represented as a declarative sentence. Revisiting the ACS-DCV function, you would write:
Use case: Access camera surveillance via the Internet—display camera views (ACS-DCV)
Actor: homeowner
1. The homeowner logs onto the SafeHome Products website. 2. The homeowner enters his or her user ID. 3. The homeowner enters two passwords (each at least eight characters in length). 4. The system displays all major function buttons. 5. The homeowner selects the “surveillance” from the major function buttons. 6. The homeowner selects “pick a camera.” 7. The system displays the floor plan of the house. 8. The homeowner selects a camera icon from the floor plan. 9. The homeowner selects the “view” button. 10. The system displays a viewing window that is identified by the camera ID. 11. The system displays video output within the viewing window at one frame per second.
134 PART TWO MODELING
It is important to note that this sequential presentation does not consider any alternative interactions (the narrative is free flowing and did represent a few alter- natives). Use cases of this type are sometimes referred to as primary scenarios [Sch98].
A description of alternative interactions is essential for a complete understanding of the function that is being described by a use case. Therefore, each step in the primary scenario is evaluated by asking the following questions [Sch98]:
∙ Can the actor take some other action at this point?
∙ Is it possible that the actor will encounter some error condition at this point? If so, what might it be?
∙ Is it possible that the actor will encounter some other behavior at this point (e.g., behavior that is invoked by some event outside the actor’s control)? If so, what might it be?
Answers to these questions result in the creation of a set of secondary scenarios that are part of the original use case but represent alternative behavior. For example, consider steps 6 and 7 in the primary scenario presented earlier:
6. The homeowner selects “pick a camera.” 7. The system displays the floor plan of the house.
Can the actor take some other action at this point? The answer is yes. Referring to the free-flowing narrative, the actor may choose to view thumbnail snapshots of all cameras simultaneously. Hence, one secondary scenario might be “View thumbnail snapshots for all cameras.”
Is it possible that the actor will encounter some error condition at this point? Any number of error conditions can occur as a computer-based system operates. In this context, we consider only error conditions that are likely as a direct result of the action described in step 6 or step 7. Again, the answer to the question is yes. A floor plan with camera icons may have never been configured. Hence, selecting “pick a camera” results in an error condition: “No floor plan configured for this house.”7 This error condition becomes a secondary scenario.
Is it possible that the actor will encounter some other behavior at this point? Again, the answer to the question is yes. As steps 6 and 7 occur, the system may encounter an alarm condition. This would result in the system displaying a special alarm noti- fication (type, location, system action) and providing the actor with several options relevant to the nature of the alarm. Because this secondary scenario can occur at any time for virtually all interactions, it will not become part of the ACS-DCV use case. Rather, a separate use case—Alarm condition encountered—would be developed and referenced from other use cases as required.
Each of the situations described in the preceding paragraphs is characterized as a use case exception. An exception describes a situation (either a failure condition or
7 In this case, another actor, the system administrator, would have to configure the floor plan, install (e.g., assign an equipment ID) all cameras and initialize them, and test each camera to be certain that it is accessible via the system and through the floor plan.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 135
an alternative chosen by the actor) that causes the system to exhibit somewhat differ- ent behavior.
Cockburn [Coc01b] recommends a “brainstorming” session to derive a reasonably complete set of exceptions for each use case. In addition to the three generic questions suggested earlier in this section, the following issues should also be explored:
∙ Are there cases in which some “validation function” occurs during this use case? This implies that the validation function is invoked, and a potential error condition might occur.
∙ Are there cases in which a supporting function (or actor) will fail to respond appropriately? For example, a user action awaits a response but the function that is to respond times out.
∙ Can poor system performance result in unexpected or improper user actions? For example, a Web-based or mobile interface responds too slowly, resulting in a user making multiple selects on a processing button. These selects queue inappropriately and ultimately generate an error condition.
The list of extensions developed by asking and answering these questions should be “rationalized” [Coc01b] using the following criteria: An exception should be noted within the use case if the software can detect the condition described and then handle the condition once it has been detected. In some cases, an exception will precipitate the development of another use case (to handle the condition noted).
8.2.3 Documenting Use Cases The informal use cases presented in Section 8.2.2 are sometimes sufficient for require- ments modeling. However, when a use case involves a critical activity or describes a complex set of steps with a significant number of exceptions, a more formal approach may be desirable.
The ACS-DCV use case shown in the sidebar follows a typical outline for formal use cases. The goal in context identifies the overall scope of the use case. The pre- condition describes what is known to be true before the use case is initiated. The trigger identifies the event or condition that “gets the use case started” [Coc01b]. The scenario lists the specific actions that are required by the actor and the appropri- ate system responses. Exceptions identify the situations uncovered as the preliminary use case is refined (Section 8.2.2). Additional headings may or may not be included and are reasonably self-explanatory.
Most developers like to create graphical representation as they create use cases out of user stories. A diagrammatic representation can facilitate better understanding of the problem by all stakeholders, particularly when the scenario is complex. As we noted earlier in this book, UML provides use case diagramming capability. Figure 8.2 depicts a use case diagram for the SafeHome product. The use case diagram helps to show the relations among the use cases in the usage scenario. Each use case is represented by an oval. Only the ACS-DCV use case has been discussed in this section.
Each modeling notation has limitations, and the UML use case is no exception. Like any other form of written description, a use case is only as good as its author(s). If the
136 PART TWO MODELING
Use Case Template for Surveillance
Use case: Access camera sur- veillance via the Internet—
display camera views (ACS-DCV) Iteration: 2, last modification: January
14 by V. Raman.
Primary actor: Homeowner.
Goal in context: To view output of cameras placed throughout the house from any remote location via the Internet.
Preconditions: System must be fully config- ured; appropriate user ID and passwords must be obtained.
Trigger: The homeowner decides to take a look inside the house while away.
Scenario: 1. The homeowner logs onto the SafeHome
Products website. 2. The homeowner enters his or her user ID. 3. The homeowner enters two passwords
(each at least eight characters in length). 4. The system displays all major function
buttons. 5. The homeowner selects the “surveillance”
button from the major function buttons. 6. The homeowner selects “pick a camera.” 7. The system displays the floor plan of the
house. 8. The homeowner selects a camera icon from
the floor plan. 9. The homeowner selects the “view” button. 10. The system displays a viewing window that
is identified by the camera ID. 11. The system displays video output within
the viewing window at one frame per second.
Exceptions: 1. ID or passwords are incorrect or not
recognized—see use case Validate ID and passwords.
2. Surveillance function not configured for this system—system displays appropriate error message; see use case Configure surveillance function.
3. Homeowner selects “View thumbnail snapshots for all camera”—see use case View thumbnail snapshots for all cameras.
4. A floor plan is not available or has not been configured—display appropriate error message and see use case Configure floor plan.
5. An alarm condition is encountered—see use case Alarm condition encountered.
Priority: Moderate priority, to be implemented after basic functions.
When available: Third increment.
Frequency of use: Infrequent.
Channel to actor: Via PC-based browser and Internet connection.
Secondary actors: System administrator, cameras.
Channels to secondary actors: 1. System administrator: PC-based system. 2. Cameras: wireless connectivity.
Open issues: 1. What mechanisms protect unauthorized
use of this capability by employees of SafeHome Products?
2. Is security sufficient? Hacking into this feature would represent a major invasion of privacy.
3. Will system response via the Internet be acceptable given the bandwidth required for camera views?
4. Will we develop a capability to provide video at a higher frames-per-second rate when high-bandwidth connections are available?
sAfeHome
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 137
description is unclear, the use case can be misleading or ambiguous. A use case focuses on function and behavioral requirements and is generally inappropriate for nonfunctional requirements. For situations in which the requirements model must have significant detail and precision (e.g., safety critical systems), a use case may not be sufficient.
However, scenario-based modeling is appropriate for a significant majority of all situations that you will encounter as a software engineer. If developed properly, the use case can provide substantial benefit as a modeling tool.
8 .3 cL A s s-BA s e d mo d e L i ng
If you look around a room, there is a set of physical objects that can be easily iden- tified, classified, and defined (in terms of attributes and operations). But when you “look around” the problem space of a software application, the classes (and objects) may be more difficult to comprehend.
8.3.1 Identifying Analysis Classes We can begin to identify classes by examining the usage scenarios developed as part of the requirements model (Section 8.2) and performing a “grammatical parse” [Abb83] on the use cases developed for the system to be built. Classes are determined by underlining each noun or noun phrase and entering it into a simple table. Synonyms should be noted. If the class (noun) is required to implement a solution, then it is part of the solution space; otherwise, if a class is necessary only to describe a solution, it is part of the problem space.
Homeowner
Access camera surveillance via
the Internet
Configures SafeHome
system parameters
Sets alarm
Cameras
SafeHome
Figure 8.2 Preliminary use case diagram for the SafeHome system
138 PART TWO MODELING
But what should we look for once all the nouns have been isolated? Analysis classes manifest themselves in one of the following ways:
∙ External entities (e.g., other systems, devices, people) that produce or con- sume information to be used by a computer-based system.
∙ Things (e.g., reports, displays, letters, signals) that are part of the information domain for the problem.
∙ Occurrences or events (e.g., a property transfer or the completion of a series of robot movements) that occur within the context of system operation.
∙ Roles (e.g., manager, engineer, salesperson) played by people who interact with the system.
∙ Organizational units (e.g., division, group, team) that are relevant to an application.
∙ Places (e.g., manufacturing floor or loading dock) that establish the context of the problem and the overall function of the system.
∙ Structures (e.g., sensors, four-wheeled vehicles, or computers) that define a class of objects or related classes of objects.
This categorization is but one of many that have been proposed in the literature.8 For example, Budd [Bud96] suggests a taxonomy of classes that includes producers (sources) and consumers (sinks) of data, data managers, view or observer classes, and helper classes.
To illustrate how analysis classes might be defined during the early stages of mod- eling, consider a grammatical parse (nouns are underlined, verbs italicized) for a processing narrative9 for the SafeHome security function.
The SafeHome security function enables the homeowner to configure the security system when it is installed, monitors all sensors connected to the security system, and interacts with the homeowner through the Internet, a PC or a control panel.
During installation, the SafeHome PC is used to program and configure the system. Each sensor is assigned a number and type, a master password is programmed for arm- ing and disarming the system, and telephone number(s) are input for dialing when a sensor event occurs.
When a sensor event is recognized, the software invokes an audible alarm attached to the system. After a delay time that is specified by the homeowner during system configura- tion activities, the software dials a telephone number of a monitoring service, provides information about the location, reporting the nature of the event that has been detected. The telephone number will be redialed every 20 seconds until telephone connection is obtained.
The homeowner receives security information via a control panel, the PC, or a browser, collectively called an interface. The interface displays prompting messages and system status information on the control panel, the PC, or the browser window. Home- owner interaction takes the following form . . .
8 Another important categorization, defining entity, boundary, and controller classes, is discussed in Section 10.3.
9 A processing narrative is similar to the use case in style but somewhat different in purpose. The processing narrative provides an overall description of the function to be developed. It is not a scenario written from one actor’s point of view. It is important to note, however, that a grammatical parse can also be used for every use case developed as part of require- ments gathering (elicitation).
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 139
Extracting the nouns, we can propose several potential classes:
Potential Class General Classification
homeowner role or external entity
sensor external entity
control panel external entity
installation occurrence
system (alias security system) thing
number, type not objects, attributes of sensor
master password thing
telephone number thing
sensor event occurrence
audible alarm external entity
monitoring service organizational unit or external entity
The list would be continued until all nouns in the processing narrative have been considered. Note that we call each entry in the list a “potential” object. We must consider each further before a final decision is made.
Coad and Yourdon [Coa91] suggest six selection characteristics that should be used as you consider each potential class for inclusion in the analysis model:
1. Retained information. The potential class will be useful during analysis only if information about it must be remembered so that the system can function.
2. Needed services. The potential class must have a set of identifiable opera- tions that can change the value of its attributes in some way.
3. Multiple attributes. During requirement analysis, the focus should be on “major” information; a class with a single attribute may, in fact, be useful during design but is probably better represented as an attribute of another class during the analysis activity.
4. Common attributes. A set of attributes can be defined for the potential class, and these attributes apply to all instances of the class.
5. Common operations. A set of operations can be defined for the potential class, and these operations apply to all instances of the class.
6. Essential requirements. External entities that appear in the problem space and produce or consume information essential to the operation of any solution for the system will almost always be defined as classes in the requirements model.
To be considered a legitimate class for inclusion in the requirements model, a potential object should satisfy most of these characteristics. The decision for inclusion of potential classes in the analysis model is somewhat subjective, and later evaluation may cause an object to be discarded or reinstated. However, the first step of class- based modeling is the definition of classes, and decisions (even subjective ones) must
140 PART TWO MODELING
be made. You should apply the selection characteristics to the list of potential SafeHome classes:
Potential Class Characteristic Number That Applies
homeowner rejected: 1, 2 fail even though 6 applies
sensor accepted: all apply
control panel accepted: all apply
installation rejected
system (alias security function) accepted: all apply
number, type rejected: 3 fails, attributes of sensor
master password rejected: 3 fails
telephone number rejected: 3 fails
sensor event accepted: all apply
audible alarm accepted: 2, 3, 4, 5, 6 apply
monitoring service rejected: 1, 2 fail even though 6 applies
It should be noted that: (1) the preceding list is not all-inclusive, so additional classes would have to be added to complete the model; (2) some of the rejected potential classes will become attributes for those classes that were accepted (e.g., number and type are attributes of Sensor, and master password and telephone number may become attributes of System); and (3) different statements of the problem might cause different “accept or reject” decisions to be made (e.g., if each homeowner had an individual password or was identified by voice print, the Homeowner class would satisfy characteristics 1 and 2 and would have been accepted).
8.3.2 Defining Attributes and Operations Attributes describe a class that has been selected for inclusion in the analysis model. It is the attributes that define the class—that clarify what is meant by the class in the context of the problem space.
To develop a meaningful set of attributes for an analysis class, you should study each use case and select those “things” that reasonably “belong” to the class. In addition, the following question should be answered for each class: What data items (composite and/or elementary) fully define this class in the context of the problem at hand?
To illustrate, we consider the System class defined for SafeHome. A homeowner can configure the security function to reflect sensor information, alarm response infor- mation, activation and deactivation information, identification information, and so forth. We can represent these composite data items in the following manner:
identification information = system ID + verification phone number + system status
alarm response information = delay time + telephone number
activation/deactivation information = master password + number of allowable tries + temporary password
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 141
Each of the data items to the right of the equal sign could be further defined to an elementary level, but for our purposes, they constitute a reasonable list of attributes for the System class (Figure 8.3).
Sensors are part of the overall SafeHome system, and yet they are not listed as data items or as attributes in Figure 8.3. Sensor has already been defined as a class, and multiple Sensor objects will be associated with the System class. In general, we avoid defining an item as an attribute if more than one of the items is to be associated with the class.
Operations define the behavior of an object. Although many different types of operations exist, they can generally be divided into four broad categories: (1) opera- tions that manipulate data in some way (e.g., adding, deleting, reformatting, selecting), (2) operations that perform a computation, (3) operations that inquire about the state of an object, and (4) operations that monitor an object for the occurrence of a control- ling event. These functions are accomplished by operating on attributes and/or asso- ciations (Section 8.3.3). Therefore, an operation must have “knowledge” of the nature of the class attributes and associations.
8.3.3 UML Class Models As a first iteration at deriving a set of operations for an analysis class, you can again study a processing narrative (or use case) and select those operations that reasonably belong to the class. To accomplish this, the grammatical parse is again studied, and verbs are isolated. Some of these verbs will be legitimate operations and can be easily
systemID verificationPhoneNumber systemStatus delayTime telephoneNumber masterPassword temporaryPassword numberTries
program() display() reset() query() arm() disarm()
System Figure 8.3
Class diagram for the System class
142 PART TWO MODELING
connected to a specific class. For example, from the SafeHome processing narrative presented earlier in this chapter, we see that “sensor is assigned a number and type” or “a master password is programmed for arming and disarming the system.” These phrases indicate several things:
∙ That an assign() operation is relevant for the Sensor class. ∙ That a program() operation will be applied to the System class. ∙ That arm() and disarm() are operations that apply to System class.
Class Models
The scene: Ed’s cubicle, as analysis modeling begins.
The players: Jamie, Vinod, and Ed, all members of the SafeHome software engineering team.
The conversation: [Ed has been working to extract classes from the use case template for ACS-DCV (presented in an earlier sidebar in this chapter) and is presenting the classes he has extracted to his colleagues.]
Ed: So, when the homeowner wants to pick a camera, he or she must pick it from a floor plan. I’ve defined a FloorPlan class. Here’s the diagram.
(They look at Figure 8.4.)
Jamie: So, FloorPlan is an object that is put to- gether with walls, doors, windows, and cameras. That’s what those labeled lines mean, right?
Ed: Yeah, they’re called “associations.” One class is associated with another according to the associations I’ve shown. [Associations are discussed in Section 8.3.3.]
Vinod: So, the actual floor plan is made up of walls and contains cameras and sensors that are placed within those walls. How does the floor plan know where to put those objects?
Ed: It doesn’t, but the other classes do. See the attributes under, say, WallSegment, which is used to build a wall. The wall segment has start and stop coordinates and the draw() operation does the rest.
Jamie: And the same goes for windows and doors. Looks like camera has a few extra attributes.
Ed: Yeah, I need them to provide pan and zoom info.
Vinod: I have a question. Why does the cam- era have an ID, but the others don’t? I notice you have an attribute called nextWall. How will WallSegment know what the next wall will be?
Ed: Good question, but as they say, that’s a design decision, so I’m going to delay that until . . .
Jamie: Give me a break . . . I’ll bet you’ve already figured it out.
Ed (smiling sheepishly): True, I’m gonna use a list structure which I’ll model when we get to design. If you get religious about separating analysis and design, the level of detail I have right here could be suspect.
Jamie: Looks pretty good to me, but I have a few more questions.
(Jamie asks questions which result in minor modifications.)
Vinod: Do you have CRC cards for each of the objects? If so, we ought to role-play through them, just to make sure nothing has been omitted.
Ed: I’m not quite sure how to do them.
Vinod: It’s not hard and they really pay off. I’ll show you.
sAfeHome
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 143
type name outsideDimensions
determineType() positionFloorplan() scale() change color()
FloorPlan
type ID location fieldView panAngle zoomSetting
determineType() translateLocation() displayID() displayView() displayZoom()
Camera type wallDimensions
determineType() computeDimensions()
Wall
type startCoordinates stopCoordinates nextWall
determineType() draw()
WallSegment type startCoordinates stopCoordinates nextWindow
determineType() draw()
Window
Is placed within
Is used to build Is used to build
Is used to build
type startCoordinates stopCoordinates nextDoor
determineType() draw()
Door
Is part of
Figure 8.4 Class diagram for FloorPlan (see sidebar discussion)
Upon further investigation, it is likely that the operation program() will be divided into several more specific suboperations required to configure the system. For example, program() implies specifying phone numbers, configuring system characteristics (e.g., creating the sensor table, entering alarm characteristics), and entering password(s). But for now, we specify program() as a single operation.
In addition to the grammatical parse, you can gain additional insight into other operations by considering the communication that occurs between objects. Objects communicate by passing messages to one another. Before continuing with the speci- fication of operations, we explore this matter in a bit more detail.
144 PART TWO MODELING
In many instances, two analysis classes are related to one another in some fashion. In UML, these relationships are called associations. Referring to Figure 8.4, the Floor- Plan class is defined by identifying a set of associations between FloorPlan and two other classes, Camera and Wall. The class Wall is associated with three classes that allow a wall to be constructed, WallSegment, Window, and Door.
8.3.4 Class-Responsibility-Collaborator Modeling Class-responsibility-collaborator (CRC) modeling [Wir90] provides a simple means for identifying and organizing the classes that are relevant to system or product requirements. A CRC model can be viewed as a collection of index cards. Each index card contains a list of responsibilities on the left side and the corresponding collabo- rations that enable the responsibilities to be fulfilled on the right side (Figure 8.5). Responsibilities are the attributes and operations that are relevant for the class. Col- laborators are those classes that provide a class with the information needed or action required to complete a responsibility. A simple CRC index card for the FloorPlan class is illustrated in Figure 8.5.
The list of responsibilities shown on the CRC card is preliminary and is subject to additions or modification. The classes Wall and Camera are noted next to the respon- sibility that requires their collaboration.
Classes. Basic guidelines for identifying classes and objects were presented ear- lier in Section 8.3.1.
Responsibilities. Basic guidelines for identifying responsibilities (attributes and operations) were presented in Section 8.3.2.
Collaborations. Classes fulfill their responsibilities in one of two ways: (1) A class can use its own operations to manipulate its own attributes, thereby fulfilling a
Class:Class:
RRR
DDD Class:Class:
RR
DD Class: FloorPlan
Responsibility: Collaborator:
Description
Defines floor plan name/type Manages floor plan positioning Scales floor plan for display Incorporates walls, doors, and windows
Shows position of video cameras
Wall Camera
Figure 8.5 A CRC model index card
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 145
responsibility itself, or (2) a class can collaborate with other classes. Collaborations are identified by determining whether a class can fulfill each responsibility itself. If it cannot, then it needs to interact with another class.
As an example, consider the SafeHome security function. As part of the activation procedure, the ControlPanel object must determine whether any sensors are open. A responsibility named determine-sensor-status() is defined. If sensors are open, ControlPanel must set a status attribute to “not ready.” Sensor information can be acquired from each Sensor object. The responsibility determine-sensor-status() can be fulfilled only if ControlPanel works in collaboration with Sensor.
Once a complete CRC model has been developed, the representatives from the stakeholders can review the model using the following approach [Amb95]:
1. All participants in the review (of the CRC model) are given a subset of the CRC model index cards. No reviewer should have two cards that collaborate.
2. The review leader reads the use case deliberately. As the review leader comes to a named object, she passes a token to the person holding the corresponding class index card.
3. When the token is passed, the holder of the class card is asked to describe the responsibilities noted on the card. The group determines whether one (or more) of the responsibilities satisfies the use case requirement.
4. If an error is found, modifications are made to the cards. This may include the definition of new classes (and corresponding CRC index cards) or revising lists of responsibilities or collaborations on existing cards.
CRC Models
The scene: Ed’s cubicle, as re- quirements modeling begins.
The players: Vinod and Ed, members of the SafeHome software engineering team.
The conversation: (Vinod has decided to show Ed how to de- velop CRC cards by showing him an example.)
Vinod: While you’ve been working on surveil- lance and Jamie has been tied up with security, I’ve been working on the home management function.
Ed: What’s the status of that? Marketing kept changing its mind.
Vinod: Here’s the first-cut use case for the whole function . . . we’ve refined it a bit, but it should give you an overall view . . .
Use case: SafeHome home management function.
Narrative: We want to use the home manage- ment interface on a mobile device or an Inter- net connection to control electronic devices that have wireless interface controllers. The system should allow me to turn specific lights on and off, to control appliances that are con- nected to a wireless interface, and to set my heating and air-conditioning system to tem- peratures that I define. To do this, I want to se- lect the devices from a floor plan of the house. Each device must be identified on the floor plan. As an optional feature, I want to control all audiovisual devices—audio, television, DVD, digital recorders, and so forth.
sAfeHome
146 PART TWO MODELING
8 .4 fu nc t i o nA L mo d e L i ng
The functional model addresses two application processing elements, each represent- ing a different level of procedural abstraction: (1) user-observable functionality that is delivered by the app to end users, and (2) the operations contained within analysis classes that implement behaviors associated with the class.
User-observable functionality encompasses any processing functions that are initiated directly by the user. For example, a financial mobile app might implement a variety of financial functions (e.g., computation of mortgage payment). These functions may be implemented using operations within analysis classes, but from the point of view of the end user, the function (more correctly, the data provided by the function) is the visible outcome.
At a lower level of procedural abstraction, the requirements model describes the processing to be performed by analysis class operations. These operations manipulate class attributes and are involved as classes collaborate with one another to accomplish some required behavior.
8.4.1 A Procedural View Regardless of the level of procedural abstraction, the UML activity diagram can be used to represent processing details. At the analysis level, activity diagrams should be used only where the functionality is relatively complex. Much of the complexity of mobile apps occurs not in the functionality provided, but rather with the nature of the information that can be accessed and the ways in which this can be manipulated.
With a single selection, I want to be able to set the entire house for various situations. One is home, another is away, a third is overnight travel, and a fourth is extended travel. All these situations will have settings that will be applied to all devices. In the overnight travel and ex- tended travel states, the system should turn lights on and off at random intervals (to make it look like someone is home) and control the heating and air-conditioning system. I should be able to override these setting via the Inter- net with appropriate password protection . . .
Ed: Do the hardware guys have all the wire- less interfacing figured out?
Vinod (smiling): They’re working on it; say it’s no problem. Anyway, I extracted a bunch of classes for home management, and we can use one as an example. Let’s use the Home- ManagementInterface class.
Ed: Okay . . . so the responsibilities are what . . . the attributes and operations for the class and the collaborations are the classes that the responsibilities point to.
Vinod: I thought you didn’t understand CRC.
Ed: So, looking at the HomeManagementInt- erface card, when the operation accessFloor- plan() is invoked, it collaborates with the FloorPlan object just like the one we devel- oped for surveillance. Wait, I have a descrip- tion of it here. (They look at Figure 8.4.)
Vinod: Exactly. And if we wanted to review the entire class model, we could start with this in- dex card, then go to the collaborator’s index card, and from there to one of the collabora- tor’s collaborators, and so on.
Ed: Good way to find omissions or errors.
Vinod: Yep.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 147
The UML activity diagram supplements the use case by providing a graphical representation of the flow of interaction within a specific scenario. An activity dia- gram is like a flowchart. The activity diagram (Figure 8.6) uses rounded rectangles to imply a specific system function, arrows to represent flow through the system, decision diamonds to depict a branching decision (each arrow emanating from the diamond is labeled), and solid horizontal lines to indicate that parallel activities are occurring.
An example of a relatively complex functionality for SafeHomeAssured.com is addressed by a use case entitled Get recommendations for sensor layout for my space. The user has already developed a layout for the space to be monitored, and in this use case, selects that layout and requests recommended locations for sensors within the layout. SafeHomeAssured.com responds with a graphical representation of the layout with additional information on the recommended locations for sensors. The interaction is quite simple and the content is somewhat more complex, but the under- lying functionality is very sophisticated. The system must undertake a relatively com- plex analysis of the floor layout to determine the optimal set of sensors. It must examine room dimensions and the location of doors and windows and coordinate these with sensor capabilities and specifications. No small task! A set of activity diagrams can be used to describe processing for this use case.
The second example is the use case Control cameras. In this use case, the interac- tion is relatively simple, but there is the potential for complex functionality, given that this “simple” operation requires complex communication with devices located remotely and accessible across the Internet. A further possible complication relates to negotia- tion of control when multiple authorized people attempt to monitor and/or control a single sensor at the same time.
requestCameraLock()
Camera not in use
Lock available Lock unavailable
Camera in use
getCurrentCameraUser()
Report Camera in use and name of current user
Report Camera unavailable
Report Camera now locked for user
L
Figure 8.6 Activity diagram for the takeControlOf Camera() operation
148 PART TWO MODELING
Figure 8.6 depicts an activity diagram for the takeControlOfCamera() operation that is part of the Camera analysis class used within the Control cameras use case. It should be noted that two additional operations are invoked with the procedural flow: requestCameraLock(), which tries to lock the camera for this user, and getCurrent- CameraUser(), which retrieves the name of the user who is currently controlling the camera. The construction details indicating how these operations are invoked and the interface details for each operation are not considered until software design commences.
8.4.2 UML Sequence Diagrams The UML sequence diagram can be used for behavioral modeling. Sequence diagrams can also be used to show how events cause transitions from object to object. Once events have been identified by examining a use case, the modeler creates a sequence diagram—a representation of how events cause flow from one object to another as a function of time. The sequence diagram is a shorthand version of the use case. It represents key classes and the events that cause behavior to flow from class to class.
Figure 8.7 illustrates a partial sequence diagram for the SafeHome security func- tion. Each of the arrows represents an event (derived from a use case) and indicates how the event channels behavior between SafeHome objects. Time is measured verti- cally (downward), and the narrow vertical rectangles represent time spent in process- ing an activity. States may be shown along a vertical time line.
Homeowner Control Panel
Reading
Comparing
Locked
Selecting
System Sensors
System Ready
Password Entered
Request Lookup
Password = correct
Request Activation
Result
Activation SuccessfulActivation Successful
numberOfTries > maxTries
Timer > lockedTime
A
T A
Figure 8.7 Sequence diagram (partial) for the SafeHome security function
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 149
The first event, system ready, is derived from the external environment and chan- nels behavior to the Homeowner object. The homeowner enters a password. A request lookup event is passed to System, which looks up the password in a simple database and returns a result (found or not found) to ControlPanel (now in the comparing state). A valid password results in a password=correct event to System, which acti- vates Sensors with a request activation event. Ultimately, control is passed back to the homeowner with the activation successful event.
Once a complete sequence diagram has been developed, all the events that cause transitions between system objects can be collated into a set of input events and out- put events (from an object). This information is useful in the creation of an effective design for the system to be built.
8 .5 Be H Av i o R A L mo d e L i ng
A behavioral model indicates how software will respond to internal or external events or stimuli. This information is useful in the creation of an effective design for the system to be built. UML activity diagrams can be used to model how system elements respond to internal events. UML state diagrams can be used to model how system elements respond to external events.
To create the model, you should perform the following steps: (1) evaluate all use cases to fully understand the sequence of interaction within the system, (2) identify events that drive the interaction sequence and understand how these events relate to specific objects, (3) create a sequence for each use case, (4) build a state diagram for the system, and (5) review the behavioral model to verify accuracy and consistency. Each of these steps is discussed in the sections that follow.
8.5.1 Identifying Events with the Use Case In Section 8.3.3, you learned that the use case represents a sequence of activities that involves actors and the system. In general, an event occurs whenever the system and an actor exchange information. An event is not the information that has been exchanged, but rather the fact that information has been exchanged.
A use case is examined for points of information exchange. To illustrate, reconsider the use case for a portion of the SafeHome security function.
The homeowner uses the keypad to key in a four-digit password. The password is com- pared with the valid password stored in the system. If the password is incorrect, the control panel will beep once and reset itself for additional input. If the password is cor- rect, the control panel awaits further action.
The underlined portions of the use case scenario indicate events. An actor should be identified for each event; the information that is exchanged should be noted, and any conditions or constraints should be listed.
As an example of a typical event, consider the underlined use case phrase “home- owner uses the keypad to key in a four-digit password.” In the context of the require- ments model, the object, Homeowner,10 transmits an event to the object ControlPanel.
10 In this example, we assume that each user (homeowner) that interacts with SafeHome has an identifying password and is therefore a legitimate object.
150 PART TWO MODELING
The event might be called password entered. The information transferred is the four digits that constitute the password, but this is not an essential part of the behavioral model. It is important to note that some events have an explicit impact on the flow of control of the use case, while others have no direct impact on the flow of control. For example, the event password entered does not explicitly change the flow of control of the use case, but the results of the event password compared (derived from the interaction “password is compared with the valid password stored in the system”) will have an explicit impact on the information and control flow of the SafeHome software.
Once all events have been identified, they are allocated to the objects involved. Objects can be responsible for generating events (e.g., Homeowner generates the password entered event) or recognizing events that have occurred elsewhere (e.g., ControlPanel recognizes the binary result of the password compared event).
8.5.2 UML State Diagrams In the context of behavioral modeling, two different characterizations of states must be considered: (1) the state of each class as the system performs its function and (2) the state of the system as observed from the outside as the system performs its function.
The state of a class takes on both passive and active characteristics [Cha93]. A passive state is simply the current values assigned to an object’s attributes. The active state of an object indicates the status of the object as it undergoes a continuing trans- formation or processing. An event (sometimes called a trigger) must occur to force an object to make a transition from one active state to another.
State Diagrams for Analysis Classes. One component of a behavioral model is a UML state diagram11 that represents active states for each class and the events (trig- gers) that cause changes between these active states. Figure 8.8 illustrates a state diagram for the ControlPanel object in the SafeHome security function.
Each arrow shown in Figure 8.8 represents a transition from one active state of an object to another. The labels shown for each arrow represent the event that triggers the transition. Although the active state model provides useful insight into the “life history” of an object, it is possible to specify additional information to provide more depth in understanding the behavior of an object. In addition to specifying the event that causes the transition to occur, you can specify a guard and an action [Cha93]. A guard is a Boolean condition that must be satisfied for the transition to occur. For example, the guard for the transition from the “reading” state to the “comparing” state in Figure 8.8 can be determined by examining the use case:
if (password input = 4 digits) then compare to stored password
In general, the guard for a transition usually depends upon the value of one or more attributes of an object. In other words, the guard depends on the passive state of the object.
11 If you are unfamiliar with UML, a brief introduction to this important modeling notation is presented in Appendix 1.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 151
An action occurs concurrently with the state transition or because of it and gener- ally involves one or more operations (responsibilities) of the object. For example, the action connected to the password entered event (Figure 8.8) is an operation named validatePassword() that accesses a password object and performs a digit-by-digit comparison to validate the entered password.
8.5.3 UML Activity Diagrams The UML activity diagram supplements the use case by providing a graphical repre- sentation of the flow of interaction within a specific scenario. Many software engi- neers like to describe activity diagrams as a way of representing how a system reacts to internal events.
An activity diagram for the ACS-DCV use case is shown in Figure 8.9. It should be noted that the activity diagram adds additional detail not directly mentioned (but implied) by the use case. For example, a user may only attempt to enter userID and password a limited number of times. A decision diamond represents this below: “Prompt for reentry.”
The UML swimlane diagram is a useful variation of the activity diagram and allows you to represent the flow of activities described by the use case and at the same time indicate which actor (if there are multiple actors involved in a specific use case) or analysis class (Section 8.3.1) has responsibility for the action described by an activity rectangle. Responsibilities are represented as parallel segments that divide the diagram vertically, like the lanes in a swimming pool.
Reading Comparing
Do: validatePassword
Locked
Selecting
Key Hit Password Entered
Password = incorrect & numberOfTries > maxTries
Password = correct
Activation Successful
numberOfTries > maxTries
Timer > lockedTime
Timer > lockedTime
Figure 8.8 State diagram for the ControlPanel class
152 PART TWO MODELING
Invalid passwords/ID
Input tries remainOther functions may also be
selected No input tries remain
Enter password and user ID
Prompt for reentry
Select major function
Thumbnail views Select a specific camera
See another cameraExit this function
Select camera icon
Select specific camera –
thumbnails
t Select
surveillance
View camera output in
labeled window
Prompt for another view
Figure 8.9 Activity diagram for Access camera surveillance via the Internet— display camera views function
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 153
Valid passwords/ID
Camera InterfaceHomeowner
Invalid passwords/ID
Input tries remain Other
functions may also be
selected No input tries remain
Enter password and user ID
Prompt for reentry
Select major function
Thumbnail views Select a specific camera
See another camera
Exit this function
Select camera icon
Select specific camera –
thumbnails
t Select
surveillance
View camera output in
labeled window
Generate video output
Prompt for another view
Figure 8.10 Swimlane diagram for Access camera surveillance via the Internet—display camera views function
Three analysis classes—Homeowner, Camera, and Interface—have direct or indirect responsibilities in the context of the activity diagram represented in Figure 8.9. Referring to Figure 8.10, the activity diagram is rearranged so that activities associated with an analysis class fall inside the swimlane for that class. For example, the Interface class represents the user interface as seen by the
154 PART TWO MODELING
homeowner. The activity diagram notes two prompts that are the responsibility of the interface—“prompt for reentry” and “prompt for another view.” These prompts and the decisions associated with them fall within the Interface swimlane. How- ever, arrows lead from that swimlane back to the Homeowner swimlane, where homeowner actions occur.
Use cases, along with the activity and swimlane diagrams, are procedurally ori- ented. Taken together they can be used to represent the way various actors invoke specific functions (or other procedural steps) to meet the requirements of the system.
8 .6 su m m A Ry
The objective of requirements modeling is to create a variety of representations that describe what the customer requires, establish a basis for the creation of a software design, and define a set of requirements that can be validated once the software is built. The requirements model bridges the gap between a system-level description that describes overall system and business functionality and a software design that describes the software’s application architecture, user interface, and component-level structure.
Scenario-based models depict software requirements from the user’s point of view. The use case—a narrative or template-driven description of an interaction between an actor and the software—is the primary modeling element. Derived dur- ing requirements elicitation, the use case defines the key steps for a specific func- tion or interaction. The degree of use case formality and detail varies, but they can provide necessary input to all other analysis modeling activities. Scenarios can also be described using an activity diagram—a graphical representation that depicts the processing flow within a specific scenario. Temporal relations in a use case can be modeled using sequence diagrams.
Class-based modeling uses information derived from use cases and other written application descriptions to identify analysis classes. A grammatical parse may be used to extract candidate classes, attributes, and operations from text-based narratives. Criteria for the definition of a class are defined using the parse results.
A set of class-responsibility-collaborator index cards can be used to define relation- ships between classes. In addition, a variety of UML modeling notation can be applied to define hierarchies, relationships, associations, aggregations, and dependencies among classes.
Behavioral modeling during requirements analysis depicts dynamic behavior of the software. The behavioral model uses input from scenario-based or class-based ele- ments to represent the states of analysis classes. To accomplish this, states are identi- fied, the events that cause a class (or the system) to make a transition from one state to another are defined, and the actions that occur as transition is accomplished are also identified. UML state diagrams, activity diagrams, swim lane diagrams, and sequence diagrams can be used for behavioral modeling.
CHAPTER 8 REQUIREMENTS MODELING—A RECOMMENDED APPROACH 155
Pro b l e m s a n d Po i n t s to Po n d e r
8.1. Is it possible to begin coding immediately after a requirements model has been created? Explain your answer, and then argue the counterpoint.
8.2. An analysis rule of thumb is that the model “should focus on requirements that are visible within the problem or business domain.” What types of requirements are not visible in these domains? Provide a few examples.
8.3. The department of public works for a large city has decided to develop a Web-based pothole tracking and repair system (PHTRS). A description follows:
Citizens can log onto a website and report the location and severity of potholes. As pot- holes are reported they are logged within a “public works department repair system” and are assigned an identifying number, stored by street address, size (on a scale of 1 to 10), location (middle, curb, etc.), district (determined from street address), and repair priority (determined from the size of the pothole). Work order data are associated with each pothole and include pothole location and size, repair crew identifying number, number of people on crew, equipment assigned, hours applied to repair, hole status (work in progress, repaired, temporary repair, not repaired), amount of filler material used, and cost of repair (computed from hours applied, number of people, material and equipment used). Finally, a damage file is created to hold information about reported damage due to the pothole and includes citizen’s name, address, phone number, type of damage, and dollar amount of damage. PHTRS is an online system; all queries are to be made interactively.
Draw a UML use case diagram PHTRS system. You’ll have to make a number of assumptions about the manner in which a user interacts with this system.
8.4. Write two or three use cases that describe the roles of various actors in the PHTRS described in Problem 8.3.
8.5. Develop an activity diagram for one aspect of PHTRS.
8.6. Develop a swimlane diagram for one or more aspects of PHTRS.
8.7. Develop a class model for the PHTRS system presented in Problem 8.3.
8.8. Develop a complete set of CRC model index cards on the product or system you chose as part of Problem 8.3.
8.9. Conduct a review of the CRC index cards with your colleagues. How many additional classes, responsibilities, and collaborators were added as a consequence of the review?
8.10. How does a sequence diagram differ from a state diagram? How are they similar?
Design element: Quick Look icon magnifying glass: © Roger Pressman
156
What is it? Design is what almost every engi- neer wants to do. It is the place where creativity rules—where requirements and technical considerations come together in the formulation of a product or system. De- sign creates a representation or model of the software and provides detail about software architecture, data structures, interfaces, and components that are necessary to imple- ment the system.
Who does it? Software engineers conduct each of the design tasks while continuing communication with the stakeholders.
Why is it important? During the design phase, you model the system or product that needs to be built. The design model can be assessed for quality and improved before code is gener- ated, tests are conducted, and end users be- come involved in large numbers.
What are the steps? Design makes use of sev- eral different representations of the software.
First, the architecture of the system or product must be modeled. Then, the interfaces that connect the software to end users, to other sys- tems and devices, and to its own constituent components are represented. Finally, the soft- ware components that are used to construct the system are designed.
What is the work product? A design model that encompasses architectural, interface, component-level, and deployment represen- tations is the primary work product that is produced during software design.
How do I ensure that I’ve done it right? The design model is assessed by the software team (including relevant stakeholders) in an effort to determine whether it contains er- rors, inconsistencies, or omissions; whether better alternatives exist; and whether the model can be implemented within the con- straints, schedule, and cost that have been established.
Q u i c k L o o k
abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 cohesion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 data design . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 design modeling principles . . . . . . . . . . . . . . 173 design process . . . . . . . . . . . . . . . . . . . . . . . . 159 functional independence . . . . . . . . . . . . . . . . 167 good design . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 information hiding . . . . . . . . . . . . . . . . . . . . . . 166
modularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 quality attributes . . . . . . . . . . . . . . . . . . . . . . . 160 quality guidelines . . . . . . . . . . . . . . . . . . . . . . 160 refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 separation of concerns . . . . . . . . . . . . . . . . . . 165 software design . . . . . . . . . . . . . . . . . . . . . . . . 157 stepwise refinement . . . . . . . . . . . . . . . . . . . . 167 technical debt . . . . . . . . . . . . . . . . . . . . . . . . . 157
k e y c o n c e p t s
C H A P T E R
9 Software design encompasses the set of principles, concepts, and practices that lead to the development of a high-quality system or product. Design principles establish an overriding philosophy that guides the design work you must perform. Design concepts must be understood before the mechanics of design practice are applied, and design practice leads to the creation of various representations of the software that serve as a guide for the construction activity that follows.
Design Concepts
CHAPTER 9 DESIGN CONCEPTS 157
Design is pivotal to successful software engineering. Some developers are tempted to begin programming once the use cases have been created, without regard to how the software components needed to implement the use cases relate to one another. It is possible to do analysis, design, and implementation iteratively by creating several software increments. It is a bad idea to ignore the design considerations needed to create an appropriate architecture for the evolving software product. Technical debt is a concept in software development that refers to costs associated with rework caused by choosing a “quick and dirty” solution right now instead of using a better approach that would take more time. It is impossible to avoid creating technical debt when build- ing a software product incrementally. However, a good development team must try to pay down this technical debt by refactoring (Section 9.3.9) the software on a regular basis. Just like taking out a loan, you can wait until the loan is due and pay a lot of interest or you can pay the loan off a little at a time and pay less interest overall.
One strategy to keep technical debt in check without delaying coding is to make use of the design practices of diversification and convergence. Diversification is the practice of identifying possible design alternatives suggested by the elements of the requirements model. Convergence is the process of evaluating and rejecting design alternatives that do not meet the constraints imposed by the nonfunctional requirements defined for the soft- ware solution. Diversification and convergence combine (1) intuition and judgment based on experience in building similar entities, (2) a set of principles and/or heuristics that guide the way in which the model evolves, (3) a set of criteria that enables quality to be judged, and (4) a process of iteration that ultimately leads to a final design representation. Once a viable design alternative is identified this way, the developers are in a good posi- tion to create a software increment that is not likely to be a throwaway prototype.
Software design changes continually as new methods, better analysis, and broader understanding evolve.1 Even today, most software design methodologies lack the depth, flexibility, and quantitative nature that are normally associated with more clas- sical engineering design disciplines. However, methods for software design do exist, criteria for design quality are available, and design notation can be applied.
In this chapter, we explore the fundamental concepts and principles that are appli- cable to all software design, the elements of the design model, and the impact of pat- terns on the design process. In Chapters 10 through 14 we’ll present a variety of software design methods as they are applied to architectural, interface, and component- level design as well as pattern-based, mobile, and user experience design approaches.
9 .1 De s i g n Wi t h i n t h e co n t e x t o f so f t Wa r e eng i n e e r i ng
Software design sits at the technical kernel of software engineering and is applied regardless of the software process model that is used. Beginning once software requirements have been analyzed and modeled, software design is the last software engineering action within the modeling activity and sets the stage for construction (code generation and testing).
1 Those readers with further interest in the philosophy of software design might have interest in Philippe Kruchen’s intriguing discussion of “postmodern” design [Kru05].
158 PART TWO MODELING
Each of the elements of the requirements model (Chapter 8) provide information that is necessary to create the four design models required for a complete specification of design. The flow of information during software design is illustrated in Figure 9.1. The requirements model, manifested by scenario-based, class-based, and behavioral elements, feed the design task. Using design notation and design methods discussed in later chapters, design produces a data/class design, an architectural design, an inter- face design, and a component design.
The data/class design transforms class models (Chapter 8) into design class realiza- tions and the requisite data structures required to implement the software. The objects and relationships defined in the CRC model and the detailed data content depicted by class attributes and other notation provide the basis for the data design activity. Part of class design may occur in conjunction with the design of software architecture. More detailed class design occurs as each software component is designed.
The architectural design defines the relationship between major structural elements of the software, the architectural style, and patterns (Chapter 14) that can be used to achieve the requirements defined for the system, and the constraints that affect the way in which architecture can be implemented [Sha15]. The architectural design representation—the framework of a computer-based system—is derived from the requirements model.
The interface design describes how the software communicates with systems that interoperate with it, and with humans who use it. An interface implies a flow of informa- tion (e.g., data and/or control) and a specific type of behavior. Therefore, usage scenarios and behavioral models provide much of the information required for interface design.
The component-level design transforms structural elements of the software architec- ture into a procedural description of software components. Information obtained from the class-based models and behavioral models serve as the basis for component design.
Component- Level Design
Interface Design
Data/Class Design
Design ModelAnalysis Model
Architectural Design
Use cases – test Use case diagrams Swimlane diagrams Sequence diagrams
Scenario-Based Elements
Class diagrams Analysis packages CRC models Collaboration diagrams
Class-Based Elements
State diagrams Activity diagrams
Behavioral Elements
Figure 9.1 Translating the requirements model into the design model
CHAPTER 9 DESIGN CONCEPTS 159
During design you make decisions that will ultimately affect the success of soft- ware construction and, just as important, the ease with which software can be main- tained. But why is design so important?
The importance of software design can be stated with a single word—quality. Design is the place where quality is fostered in software engineering. It provides you with representations of software that can be assessed for quality. Design is the only way that you can accurately translate stakeholders’ requirements into a finished software product or system. Software design serves as the foundation for all the software engineering and software support activities that follow. Without design, you risk building an unstable system—one that will fail when small changes are made; one that may be difficult to test; one whose quality cannot be assessed until late in the software process. Late in the project is when time is short, and many budgeted dollars have already been spent.
Design Versus Coding
The scene: Jamie’s cubicle, as the team prepares to translate
requirements into design.
The players: Jamie, Vinod, and Ed, all members of the SafeHome software engineering team.
The conversation: Jamie: You know, Doug [the team manager] is obsessed with design. I gotta be honest, what I really love doing is coding. Give me C++ or Java, and I’m happy.
Ed: Nah . . . you like to design.
Jamie: You’re not listening—coding is where it’s at.
Vinod: I think what Ed means is that you don’t really like coding; you like to design and ex- press it in code. Code is the language you use to represent the design.
Jamie: And what’s wrong with that?
Vinod: Level of abstraction.
Jamie: Huh?
Ed: A programming language is good for rep- resenting details like data structures and algo- rithms, but it’s not so good for representing architecture or component-to-component collaboration . . . stuff like that.
Vinod: And a screwed-up architecture can ruin even the best code.
Jamie (thinking for a minute): So, you’re saying that I can’t represent architecture in code . . . that’s not true.
Vinod: You can certainly imply architecture in code, but in most programming languages, it’s difficult to get a quick, big-picture read on architecture by examining the code.
Ed: And that’s what we want before we begin coding.
Jamie: Okay, maybe design and coding are different, but I still like coding better.
safehome
9.2 th e De s i g n pro c e s s
Software design is an iterative process through which requirements are translated into a “blueprint” for constructing the software. Initially, the blueprint depicts a holistic view of software. That is, the design is represented at a high level of abstraction—a level that can be directly traced to the specific system objective and more detailed data, functional, and behavioral requirements. As design iterations occur, subsequent
160 PART TWO MODELING
refinement leads to design representations at much lower levels of abstraction. These can still be traced to requirements, but the connections may not be obvious at these lower levels of abstraction.
9.2.1 Software Quality Guidelines and Attributes Throughout the design process, the quality of the evolving design is assessed with a series of technical reviews discussed in Chapter 16. McGlaughlin [McG91] suggests three characteristics that serve as a guide for the evaluation of a good design:
∙ The design should implement all explicit requirements contained in the requirements model, and it must accommodate all the implicit requirements desired by stakeholders.
∙ The design should be a readable, understandable guide for those who generate code and for those who test and subsequently support the software.
∙ The design should provide a complete picture of the software, addressing the data, functional, and behavioral domains from an implementation perspective.
Each of these characteristics is a goal of the design process. But how is each of these goals achieved?
Quality Guidelines. To evaluate the quality of a design representation, you and other members of the software team must establish technical criteria for good design. In Section 9.3, we discuss design concepts that also serve as software quality criteria. For the time being, consider the following guidelines:
1. A design should exhibit an architecture that (a) has been created using recog- nizable architectural styles or patterns, (b) is composed of components that exhibit good design characteristics (these are discussed later in this chapter), and (c) can be implemented in an evolutionary fashion,2 thereby facilitating implementation and testing.
2. A design should be modular; that is, the software should be logically partitioned into elements or subsystems.
3. A design should contain distinct representations of data, architecture, interfaces, and components.
4. A design should lead to data structures that are appropriate for the classes to be implemented and are drawn from recognizable data patterns.
5. A design should lead to components that exhibit independent functional characteristics.
6. A design should lead to interfaces that reduce the complexity of connections between components and with the external environment.
7. A design should be derived using a repeatable method that is driven by information obtained during software requirements analysis.
8. A design should be represented using a notation that effectively communicates its meaning.
2 For smaller systems, design can sometimes be developed linearly.
CHAPTER 9 DESIGN CONCEPTS 161
Chance alone will not achieve these design guidelines. They are achieved through the application of fundamental design principles, systematic methodology, and thorough review.
Assessing Design Quality—The Technical Review
Design is important because it allows a software team to assess the quality3
of the software before it is implemented—at a time when errors, omissions, or inconsistencies are easy and inexpensive to correct. But how do we assess quality during design? The software can’t be tested, because there is no executable soft- ware to test. What to do?
During design, quality is assessed by conduct- ing a series of technical reviews (TRs). TRs are dis- cussed in detail in Chapter 16,4 but it’s worth providing a summary of the technique at this point. A technical review is a meeting conducted by members of the software team. Usually two, three, or four people participate depending on the
scope of the design information to be reviewed. Each person plays a role. The review leader plans the meeting, sets an agenda, and runs the meet- ing; the recorder takes notes so that nothing is missed; and the producer is the person whose work product (e.g., the design of a software com- ponent) is being reviewed. Prior to the meeting, each person on the review team is given a copy of the design work product and is asked to read it, looking for errors, omissions, or ambiguity. When the meeting commences, the intent is to note all problems with the work product so that they can be corrected before implementation begins. The TR typically lasts between 60 to 90 minutes. After the TR concludes, the review team determines whether further actions are required from the producer before the design work product can be approved as part of the final design model.
info
3 The quality factors discussed in Chapter 23 can assist the review team as it assesses quality. 4 You might consider looking ahead to Chapter 16 at this time. Technical reviews are a critical
part of the design process and are an important mechanism for achieving design quality.
9.2.2 The Evolution of Software Design The evolution of software design is a continuing process that has now spanned more than six decades. Early design work concentrated on criteria for the development of modular programs [Den73] and methods for refining software structures in a top-down “structured” manner ([Wir71], [Dah72], [Mil72]). Newer design approaches (e.g., [Jac92], [Gam95]) proposed an object-oriented approach to design derivation. More recent emphasis in software design has been on software architecture [Kru06] and the design patterns that can be used to implement software architectures and lower levels of design abstractions (e.g., [Hol06], [Sha05]). There is a growing emphasis on aspect- oriented methods (e.g., [Cla05], [Jac04]), model-driven development [Sch06], and test-driven development [Ast04], which focus on techniques for achieving more effec- tive modularity and architectural structure in the designs that are created.
In the past 10 years, Search-Based Software Engineering (SBSE) techniques have been applied to all phases of the software engineering life cycle, including design [Har12]. SBSE attempts to solve software engineering problems using automated search tech- niques augmented by operations research and machine learning algorithms to provide design recommendations to software developers. Many modern software systems must accommodate a high degree of variability, both in their deployment environments and
162 PART TWO MODELING
the number of usage scenarios they expected to satisfy. Design of variability-intensive systems5 requires developers to anticipate future changes in the features to be modified in future versions of the product being designed today [Gal16]. A detailed discussion of the design of variability-intensive systems is beyond the scope of this book.
Several design methods, growing out of the work just noted, are being applied through- out the industry. Like the analysis methods presented in Chapter 8, each software design method introduces unique heuristics and notation, as well as a somewhat parochial view of what characterizes design quality. Yet, each of these methods has common character- istics: (1) a mechanism for the translation of the requirements model into a design rep- resentation, (2) a notation for representing functional components and their interfaces, (3) heuristics for refinement and partitioning, and (4) guidelines for quality assessment.
Regardless of the design method that is used, you should apply a set of basic concepts to data, architectural, interface, and component-level design. These concepts are considered in the sections that follow.
5 Variability-intensive systems refers to systems that may be required to be self-modifying based on changes in the run-time environment or families of software products resulting from product line engineering practices for building specialized product variants out of existing software products.
Generic Task Set for Design Please note: These tasks are often per- formed iteratively and in parallel. They
are rarely completed sequentially and in isolation from one another unless you are following the waterfall process model.
1. Examine the information model, and design appropriate data structures for data objects and their attributes.
2. Using the analysis model, select an architec- tural style (pattern) that is appropriate for the software.
3. Partition the analysis model into design subsystems and allocate these subsystems within the architecture:
Be certain that each subsystem is func- tionally cohesive.
Design subsystem interfaces. Allocate analysis classes or functions to
each subsystem. 4. Create a set of design classes or components:
Translate an analysis class description into a design class.
Check each design class against design criteria; consider inheritance issues.
Define methods and messages associated with each design class.
Evaluate and select design patterns for a design class or a subsystem.
Review design classes and revise as required.
5. Design any interface required with external systems or devices.
6. Design the user interface: Review results of task analysis. Specify action sequence based on user
scenarios. Create a behavioral model of the interface. Define interface objects and control
mechanisms. Review the interface design, and revise as
required. 7. Conduct component-level design. Specify
all algorithms at a relatively low level of abstraction.
Refine the interface of each component. Define component-level data structures. Review each component, and correct all
errors uncovered. 8. Develop a deployment model.
task set
CHAPTER 9 DESIGN CONCEPTS 163
9 .3 De s i g n co nc e p t s
Several fundamental software design concepts have evolved over the history of soft- ware engineering. Although the degree of interest in these concepts has varied over the years, each has stood the test of time. Each provides the software designer with a foundation from which more sophisticated design methods can be applied. Each helps you define criteria that can be used to partition software into individual com- ponents, separate out data structure detail from a conceptual representation of the software, and establish uniform criteria that define the technical quality of a software design. These concepts help developers design the software actually needed, rather than simply focusing on creating any old working program.
9.3.1 Abstraction When you consider a modular solution to any problem, many levels of abstraction can be posed. At the highest level of abstraction, a solution is stated in broad terms using the language of the problem environment (e.g., a user story). At lower levels of abstraction, a more detailed description of the solution is provided. Problem-oriented terminology is coupled with implementation-oriented terminology to state a solution (e.g., use case). Finally, at the lowest level of abstraction, the solution is stated in a manner that can be directly implemented (e.g., pseudocode).
As different levels of abstraction are developed, you work to create both procedural and data abstractions. A procedural abstraction refers to a sequence of instructions that have a specific and limited function. The name of a procedural abstraction implies these functions, but specific details are suppressed. An example of a procedural abstraction would be the word use for a camera in the SafeHome system. Use implies a long sequence of procedural steps (e.g., activate the SafeHome system on a mobile device, log on to the SafeHome system, select a camera to preview, locate the camera controls on mobile app user interface, etc.).6
A data abstraction is a named collection of data that describes a data object. In the context of the procedural abstraction open, we can define a data abstraction called camera. Like any data object, the data abstraction for camera would encompass a set of attributes that describe the camera (e.g., camera ID, location, field view, pan angle, zoom). It follows that the procedural abstraction use would make use of infor- mation contained in the attributes of the data abstraction camera.
9.3.2 Architecture Software architecture alludes to “the overall structure of the software and the ways in which that structure provides conceptual integrity for a system” [Sha15]. In its sim- plest form, architecture is the structure or organization of program components (mod- ules), the ways in which these components interact, and the structure of data that are
6 It should be noted, however, that one set of operations can be replaced with another, if the function implied by the procedural abstraction remains the same. Therefore, the steps required to implement use would change dramatically if the camera were automatic and attached to a sensor that automatically triggered an alert on your mobile device.
164 PART TWO MODELING
used by the components. In a broader sense, however, components can be generalized to represent major system elements and their interactions.
One goal of software design is to derive an architectural rendering of a system. This rendering serves as a framework from which more detailed design activities are conducted. A set of architectural patterns enables a software engineer to reuse design- level concepts.
Shaw and Garlan [Sha15] describe a set of properties that should be specified as part of an architectural design. Structural properties define “the components of a system (e.g., modules, objects, filters) and the manner in which those components are packaged and interact with one another.” Extra-functional properties address “how the design architecture achieves requirements for performance, capacity, reliability, security, adaptability, and other system characteristics (e.g., nonfunctional system requirements).” Families of related systems “draw upon repeatable patterns that are commonly encountered in the design of families of similar systems.”7
Given the specification of these properties, the architectural design can be repre- sented using one or more of several different models [Gar95]. Structural models rep- resent architecture as an organized collection of program components. Framework models increase the level of design abstraction by attempting to identify repeatable architectural design frameworks (patterns) that are encountered in similar types of applications. Dynamic models address the behavioral aspects of the program architec- ture, indicating how the structure or system configuration may change as a function of external events. Process models focus on the design of the business or technical process that the system must accommodate. Finally, functional models can be used to represent the functional hierarchy of a system.
Several different architectural description languages (ADLs) have been developed to represent these models [Sha15]. Although many different ADLs have been pro- posed, the majority provide mechanisms for describing system components and the ways in which they are connected to one another.
You should note that there is some debate about the role of architecture in design. Some researchers argue that the derivation of software architecture should be sepa- rated from design and occurs between requirements engineering actions and more conventional design actions. Others believe that the derivation of architecture is an integral part of the design process. The ways in which software architecture is char- acterized and its role in design are discussed in Chapter 10.
9.3.3 Patterns Brad Appleton defines a design pattern in the following manner: “A pattern is a named nugget of insight which conveys the essence of a proven solution to a recurring prob- lem within a certain context amidst competing concerns” [App00]. Stated in another way, a design pattern describes a design structure that solves a well-defined design problem within a specific context and amid “forces” that may have an impact on the manner in which the pattern is applied and used.
7 These families of related software products sharing common features are called software product lines.
CHAPTER 9 DESIGN CONCEPTS 165
The intent of each design pattern is to provide a description that enables a designer to determine (1) whether the pattern is applicable to the current work, (2) whether the pattern can be reused (hence, saving design time), and (3) whether the pattern can serve as a guide for developing a similar, but functionally or structurally different, pattern. Design patterns are discussed in detail in Chapter 14.
9.3.4 Separation of Concerns Separation of concerns is a design concept [Dij82] that suggests that any complex prob- lem can be more easily handled if it is subdivided into pieces that can each be solved and/or optimized independently. A concern is a feature or behavior that is specified as part of the requirements model for the software. By separating concerns into smaller and therefore more manageable pieces, a problem takes less effort and time to solve.
It follows that the perceived complexity of two problems when they are combined is often greater than the sum of the perceived complexity when each is taken sepa- rately. This leads to a divide-and-conquer strategy—it’s easier to solve a complex problem when you break it into manageable pieces. This has important implications for software modularity.
Separation of concerns is manifested in other related design concepts: modularity, functional independence, and refinement. Each will be discussed in the subsections that follow.
9.3.5 Modularity Modularity is the most common manifestation of separation of concerns. Software is divided into separately named and addressable components, sometimes called modules, that are integrated to satisfy problem requirements.
It has been stated that “modularity is the single attribute of software that allows a program to be intellectually manageable” [Mye78]. Monolithic software (i.e., a large program composed of a single module) cannot be easily grasped by a software engi- neer. The number of control paths, span of reference, number of variables, and over- all complexity would make understanding close to impossible. In almost all instances, you should break the design into many modules, hoping to make understanding easier and reduce the cost required to build the software.
Recalling our discussion of separation of concerns, it is possible to conclude that if you subdivide software indefinitely the effort required to develop it will become negligibly small! Unfortunately, other forces come into play, causing this conclusion to be (sadly) invalid. Referring to Figure 9.2, the effort (cost) to develop an individual software module tends to decrease as the total number of modules increases.
Given the same set of requirements, the more modules used in your program means smaller individual sizes. However, as the number of modules grows, the effort (cost) associated with integrating modules with each other grows. These characteristics lead to a total cost or effort curve, shown in Figure 9.2. There is a number, M, of modules that would result in minimum development cost, but we do not have the necessary sophistication to predict M with assurance.
The curves shown in Figure 9.2 do provide useful qualitative guidance when mod- ularity is considered. You should modularize, but care should be taken to stay in the vicinity of M. Using too few modules or too many modules should be avoided.
166 PART TWO MODELING
But how do you know the vicinity of M? How modular should you make software? The answers to these questions require an understanding of other design concepts considered in Sections 9.3.6 through 9.3.9.
You modularize a design (and the resulting program) so that development can be more easily planned, software increments can be defined and delivered, changes can be more easily accommodated, testing and debugging can be conducted more effi- ciently, and long-term maintenance can be conducted without serious side effects.
9.3.6 Information Hiding The concept of modularity leads you to a fundamental question: “How do I decompose a software solution to obtain the best set of modules?” The principle of information hiding [Par72] suggests that modules should be “characterized by design decisions that (each) hides from all others.” In other words, modules should be specified and designed so that information (algorithms and data) contained within a module is inac- cessible to other modules that have no need for such information.
Hiding implies that effective modularity can be achieved by defining a set of inde- pendent modules that communicate with one another only that information necessary to achieve software function. Abstraction helps to define the procedural (or informa- tional) entities that make up the software. Hiding defines and enforces access con- straints to both procedural detail within a module and any local data structure used by the module [Ros75].
The use of information hiding as a design criterion for modular systems provides the greatest benefits when modifications are required during testing and later during software maintenance. Because most data and procedural detail are hidden from other parts of the software, inadvertent errors introduced during modification are less likely to propagate to other locations within the software.
Region of minimum cost
M
Number of modules
C os
t o f e
�o rt
Total software cost
Cost to integrate
Cost/module
}
Figure 9.2 Modularity and software cost
CHAPTER 9 DESIGN CONCEPTS 167
9.3.7 Functional Independence The concept of functional independence is a direct outgrowth of separation of con- cerns, modularity, and the concepts of abstraction and information hiding. In landmark papers on software design, Wirth [Wir71] and Parnas [Par72] each allude to refine- ment techniques that enhance module independence. Later work by Stevens, Myers, and Constantine [Ste74] solidified the concept.
Functional independence is achieved by developing modules with “single-minded” function and an “aversion” to excessive interaction with other modules. Stated another way, you should design software so that each module addresses a specific subset of requirements and has a simple interface when viewed from other parts of the program structure.
It is fair to ask why independence is important. Software with effective modularity, that is, independent modules, is easier to develop because function can be compart- mentalized and interfaces are simplified (consider the ramifications when development is conducted by a team). Independent modules are easier to maintain (and test) because secondary effects caused by design or code modification are limited, error propagation is reduced, and reusable modules are possible. To summarize, functional independence is a key to good design, and design is the key to software quality. Evaluation of your CRC card model (Chapter 8) can help you spot problems with functional independence. User stories that contain many instances of words such as and or except are not likely to encourage you to design modules that are “single-minded” system functions.
Independence is assessed using two qualitative criteria: cohesion and coupling. Cohesion is an indication of the relative functional strength of a module. Coupling is an indication of the relative interdependence among modules.
Cohesion is a natural extension of the information-hiding concept described in Sec- tion 9.3.6. A cohesive module performs a single task, requiring little interaction with other components in other parts of a program. Stated simply, a cohesive module should (ideally) do just one thing. Although you should always strive for high cohesion (i.e., single-mindedness), it is often necessary and advisable to have a software component perform multiple functions. However, “schizophrenic” components (modules that per- form many unrelated functions) are to be avoided if a good design is to be achieved.
Coupling is an indication of interconnections among modules in a software struc- ture. Coupling depends on the interface complexity between modules, the point at which entry or reference is made to a module, and what data pass across the interface. In software design, you should strive for the lowest possible coupling. Simple con- nectivity among modules results in software that is easier to understand and less likely to propagate errors found in one module to other system modules.
9.3.8 Stepwise Refinement Stepwise refinement is a top-down design strategy originally proposed by Niklaus Wirth [Wir71]. Successively refining levels of procedural detail is a good way to develop an application. A hierarchy is developed by decomposing a macroscopic statement of function (a procedural abstraction) in a stepwise fashion until program- ming language statements are reached.
Refinement is a process of elaboration. You begin with a statement of function (or description of information) that is defined at a high level of abstraction. That is, the
168 PART TWO MODELING
statement describes function or information conceptually but provides no indication of the internal workings of the function or the internal structure of the information. You then elaborate on the original statement, providing more detail as each successive refinement (elaboration) occurs.
Abstraction and refinement are complementary concepts. Abstraction enables you to specify procedure and data internally but suppress the need for “outsiders” to have knowledge of low-level details. Refinement helps you to reveal low-level details as design progresses. Both concepts allow you to create a complete design model as the design evolves.
9.3.9 Refactoring An important design activity suggested for many agile methods (Chapter 3), refactor- ing is a reorganization technique that simplifies the design (or code) of a component without changing its function or behavior. Fowler [Fow00] defines refactoring in the following manner: “Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code [design] yet improves its internal structure.”
When software is refactored, the existing design is examined for redundancy, unused design elements, inefficient or unnecessary algorithms, poorly constructed or inappropriate data structures, or any other design failure that can be corrected to yield a better design. For example, a first design iteration might yield a large component that exhibits low cohesion (i.e., it performs three functions that have only a limited relationship to one another). After careful consideration, you may decide that the component should be refactored into three separate components, each of which exhib- its high cohesion. The result will be software that is easier to integrate, easier to test, and easier to maintain.
Although the intent of refactoring is to modify the code in a manner that does not alter its external behavior, inadvertent side effects can and do occur. Refactoring tools [Soa10] are sometimes used to analyze code changes automatically and to “generate a test suite suitable for detecting behavioral changes.”
Design Concepts
The scene: Vinod’s cubicle, as design modeling begins.
The players: Vinod, Jamie, and Ed—members of the SafeHome software engineering team. Also, Shakira, a new member of the team.
The conversation: (All four team members have just returned from a morning seminar entitled “Applying Basic Design Concepts,” offered by a local computer science professor.)
Vinod: Did you get anything out of the seminar?
Ed: Knew most of the stuff, but it’s not a bad idea to hear it again, I suppose.
Jamie: When I was an undergrad CS major, I never really understood why information hiding was as important as they say it is.
Vinod: Because . . . bottom line . . . it’s a technique for reducing error propagation in a program. Actually, functional independence also accomplishes the same thing.
safehome
CHAPTER 9 DESIGN CONCEPTS 169
9.3.10 Design Classes The analysis model defines a set of analysis classes (Chapter 8). Each of these classes describes some element of the problem domain, focusing on aspects of the problem that are user visible. The level of abstraction of an analysis class is relatively high.
As the design model evolves, you will define a set of design classes that refine the analysis classes by providing design detail that will enable the classes to be imple- mented and to create a software infrastructure that supports the business solution.
As the software architecture forms, the level of abstraction is reduced as each analysis class (Chapter 8) is transformed into a design representation. That is, analy- sis classes represent data objects and associated services that are applied to them. Design classes present significantly more technical detail as a guide for implementation.
Arlow and Neustadt [Arl02] suggest that each design class be reviewed to ensure that it is “well-formed.” They define four characteristics of a well-formed design class:
Complete and sufficient. A design class should be the complete encapsulation of all attributes and methods that can reasonably be expected (based on a knowledgeable interpretation of the class name) to exist for the class. For example, the class Floor- Plan (Figure 9.3) defined for the SafeHome room layout software is complete only if it contains all attributes and methods that can reasonably be associated with the cre- ation of a floor plan. Sufficiency ensures that the design class contains only those methods that are sufficient to achieve the intent of the class, no more and no less.
Primitiveness. Methods associated with a design class should be focused on accomplishing one service for the class. Once the service has been implemented with a method, the class should not provide another way to accomplish the same thing. For example, the class Segment (Figure 9.3) for use by the room layout
Shakira: I wasn’t an SE grad, so a lot of the stuff the instructor mentioned is new to me. I can generate good code and fast. I don’t see why this stuff is so important.
Jamie: I’ve seen your work, Shak, and you know what, you do a lot of this stuff natu- rally . . . that’s why your designs and code work.
Shakira (smiling): Well, I always do try to parti- tion the code, keep it focused on one thing, keep interfaces simple and constrained, reuse code whenever I can . . . that sort of thing.
Ed: Modularity, functional independence, hiding, patterns . . . see.
Jamie: I still remember the very first program- ming course I took . . . they taught us to refine the code iteratively.
Vinod: Same thing can be applied to design, you know.
Jamie: The only concepts I hadn’t heard of before were “design classes” and “refactoring.”
Shakira: Refactoring is used in Extreme Programming, I think she said.
Ed: Yep. It’s not a whole lot different than refinement, only you do it after the design or code is completed. Kind of like an optimization pass through the software, if you ask me.
Jamie: Let’s get back to the SafeHome de- sign. I think we should put these concepts on our review checklist as we develop the design model for SafeHome.
Vinod: I agree. But as important, let’s all commit to think about them as we develop the design.
170 PART TWO MODELING
software might have attributes startCoordinate and endCoordinate to indicate the start and end points of the segment to be drawn. The method setCoordinates() provides the only means for establishing start and end points for the segment.
High cohesion. A cohesive design class has a small, focused set of responsibili- ties and single-mindedly applies attributes and methods to implement those respon- sibilities. For example, the class FloorPlan (Figure 9.3) might contain a set of methods for editing the house floor plan. As long as each method focuses solely on attributes associated with the floor plan, cohesion is maintained.
Low coupling. Within the design model, it is necessary for design classes to col- laborate with one another. However, collaboration should be kept to an acceptable minimum. If a design model is highly coupled (all design classes collaborate with all other design classes), the system is difficult to implement, to test, and to maintain over time. In general, design classes within a subsystem should have only limited knowledge of other classes. This restriction, called the Law of Demeter [Lie03], sug- gests that a method should only send messages to methods in neighboring classes.8
8 A less formal way of stating the Law of Demeter is “Each unit should only talk to its friends; don’t talk to strangers.”
startCoordinate endCoordinate
getType() draw()
Segment
type outsideDimensions
addCamera() addWall() addWindow() deleteSegment() draw()
FloorPlan
type ID fieldView panAngle zoomSetting
Camera
WallSegment Window
1
1
*
*
Figure 9.3 Design class for FloorPlan and composite aggregation for the class (see sidebar discussion)
CHAPTER 9 DESIGN CONCEPTS 171
9 .4 th e De s i g n mo D e L
The software design model is the equivalent of an architect’s plans for a house. It begins by representing the totality of the thing to be built (e.g., a three-dimensional rendering of the house) and slowly refines the thing to provide guidance for construct- ing each detail (e.g., the plumbing layout). Similarly, the design model that is created for software provides a variety of different views of the system.
The design model can be viewed in two different dimensions, as illustrated in Figure 9.4. The process dimension indicates the evolution of the design model as design tasks are executed as part of the software process. The abstraction dimension represents the level of detail as each element of the analysis model is transformed into a design equivalent and then refined iteratively. Referring to the figure, the dashed line indicates the boundary between the analysis and design models. In some cases, a clear distinction between the analysis and design models is possible. In other cases, the analysis model slowly blends into the design and a clear distinction is less obvious.
Refining an Analysis Class into a Design Class
The scene: Ed’s cubicle, as design modeling begins.
The players: Vinod and Ed, members of the SafeHome software engineering team.
The conversation: [Ed is working on the FloorPlan class (see side- bar discussion in Section 8.3.3 and Figure 8.4) and has refined it for the design model.]
Ed: So you remember the FloorPlan class, right? It’s used as part of the surveillance and home management functions.
Vinod (nodding): Yeah, I seem to recall that we used it as part of our CRC discussions for home management.
Ed: We did. Anyway, I’m refining it for design. I want to show how we’ll actually implement the FloorPlan class. My idea is to implement it as a set of linked lists [a specific data structure]. So . . . I had to refine the analysis class Floor- Plan (Figure 8.4) and actually, sort of simplify it.
Vinod: The analysis class showed only things in the problem domain, well, actually on the
computer screen, that were visible to the end user, right?
Ed: Yep, but for the FloorPlan design class, I’ve got to add some things that are implemen- tation specific. I needed to show that Floor- Plan is an aggregation of segments—hence the Segment class—and that the Segment class is composed of lists for wall segments, windows, doors, and so on. The class Camera collaborates with FloorPlan, and obviously, there can be many cameras in the floor plan.
Vinod: Phew, let’s see a picture of this new FloorPlan design class.
(Ed shows Vinod the drawing shown in Figure 9.3.)
Vinod: Okay, I see what you’re trying to do. This allows you to modify the floor plan easily because new items can be added to or de- leted from the list—the aggregation—without any problems.
Ed (nodding): Yeah, I think it’ll work.
Vinod: So do I.
safehome
172 PART TWO MODELING
The elements of the design model use many of the same UML diagrams9 that were used in the analysis model. The difference is that these diagrams are refined and elaborated as part of design; more implementation-specific detail is provided, and architectural structure and style, components that reside within the architec- ture, and interfaces between the components and with the outside world are all emphasized.
You should note, however, that model elements indicated along the horizontal axis are not always developed in a sequential fashion. In most cases, preliminary architec- tural design sets the stage and is followed by interface design and component-level design, which often occur in parallel. The deployment model is usually delayed until the design has been fully developed.
You can apply design patterns (Chapter 14) at any point during design. These pat- terns enable you to apply design knowledge to domain-specific problems that have been encountered and solved by others.
Low
High
Process dimension
A bs
tr ac
tio n
di m
en si
on
Architecture elements
Class diagrams Analysis packages CRC models Collaboration diagrams Processing narratives
Uses cases – text Use case diagrams Swimlane diagrams Collaboration diagrams State diagrams Sequence diagrams
Technical interface design Navigation design GUI design
Design class realizations Subsystems Collaboration diagrams
Refinements to: Design class realizations Subsystems Collaboration diagrams
Interface elements
Component-level elements
Deployment-level elements
Analysis model
Design model
Class diagrams Analysis packages CRC models Collaboration diagrams Processing narratives State diagrams Sequence diagrams
Component diagrams Design classes Activity diagrams Sequence diagrams
Design class realizations Subsystems Collaboration diagrams Component diagrams Design classes Activity diagrams Sequence diagrams
Deployment diagrams
Component diagrams Design classes Activity diagrams Sequence diagrams
Refinements to: Component diagrams Design classes Activity diagrams Sequence diagrams
Requirements: Constraints Interoperability Targets and configuration
Figure 9.4 Dimensions of the design model
9 Appendix 1 provides a tutorial on basic UML concepts and notation.
CHAPTER 9 DESIGN CONCEPTS 173
9.4.1 Design Modeling Principles There is no shortage of methods for deriving the various elements of a software design model. Some methods are data driven, allowing the data structure to dictate the program architecture and the resultant processing components. Others are pattern driven, using information about the problem domain (the requirements model) to develop architectural styles and processing patterns. Still others are object oriented, using problem domain objects as the driver for the creation of data structures and the methods that manipulate them. Yet all embrace a set of design principles that can be applied, regardless of the method that is used:
Principle 1. Design should be traceable to the requirements model. The requirements model describes the information domain of the problem, user- visible functions, system behavior, and a set of requirements classes that package business objects with the methods that service them. The design model translates this information into an architecture, a set of subsystems that implement major functions, and a set of components that are the realization of requirements classes. The elements of the design model should be traceable to the require- ments model.
Principle 2. Always consider the architecture of the system to be built. Soft- ware architecture (Chapter 10) is the skeleton of the system to be built. It affects interfaces, data structures, program control flow and behavior, the manner in which testing can be conducted, the maintainability of the resultant system, and much more. For all these reasons, design should start with architectural consider- ations. Only after the architecture has been established should component-level issues be considered.
Principle 3. Design of data is as important as design of processing functions. Data design is an essential element of architectural design. The ways in which data objects are realized within the design cannot be left to chance. A well-structured data design helps to simplify program flow, makes the design and implementation of software components easier, and makes overall processing more efficient.
Principle 4. Interfaces (both internal and external) must be designed with care. The ways in which data flows between the components of a system has much to do with processing efficiency, error propagation, and design simplicity. A well- designed interface makes integration easier and assists the tester in validating component functions.
Principle 5. User interface design should be tuned to the needs of the end user. However, in every case, it should stress ease of use. The user interface is the visible manifestation of the software. No matter how sophisticated its internal functions, no matter how comprehensive its data structures, no matter how well designed its architecture, a poor interface design often leads to the perception that the software is “bad.”
Principle 6. Component-level design should be functionally independent. Functional independence is a measure of the “single-mindedness” of a software component. The functionality that is delivered by a component should be cohesive— that is, it should focus on one and only one function.
174 PART TWO MODELING
Principle 7. Components should be loosely coupled to one another and to the external environment. Coupling is achieved in many ways—via a component interface, by messaging, and through global data. As the level of coupling increases, the likeli- hood of error propagation also increases and the overall maintainability of the software decreases. Therefore, component coupling should be kept as low as is reasonable.
Principle 8. Design representations (models) should be easily understandable. The purpose of design is to communicate information to practitioners who will gen- erate code, to those who will test the software, and to others who may maintain the software in the future. If the design is difficult to understand, it will not serve as an effective communication medium.
Principle 9. The design should be developed iteratively. With each iteration, the designer should strive for greater simplicity. Like almost all creative activities, design occurs iteratively. The first iterations work to refine the design and correct errors, but later iterations should strive to make the design as simple as is possible.
Principle 10. Creation of a design model does not preclude an agile approach. Some proponents of agile software development (Chapter 3) insist that the code is the only design documentation that is needed. Yet the purpose of a design model is to help others who must maintain and evolve the system. It is extremely difficult to understand either the higher-level purpose of a code fragment or its interactions with other modules in a modern multithreaded run-time environment.
Agile design documentation should be kept in sync with the design and develop- ment, so that at the end of the project the design is documented at a level that allows the code to be understood and maintained. The design model provides benefit because it is created at a level of abstraction that is stripped of unnecessary technical detail and is closely coupled to the application concepts and requirements. Complementary design information can incorporate a design rationale, including the descriptions of rejected architectural design alternatives.
9.4.2 Data Design Elements Like other software engineering activities, data design (sometimes referred to as data architecting) creates a model of data and/or information that is represented at a high level of abstraction (the customer or user’s view of data). This data model is then refined into progressively more implementation-specific representations that can be processed by the computer-based system. In many software applications, the architec- ture of the data will have a profound influence on the architecture of the software that must process it.
The structure of data has always been an important part of software design. At the program-component level, the design of data structures and the associated algorithms required to manipulate them is essential to the creation of high-quality applications. At the application level, the translation of a data model (derived as part of require- ments engineering) into a database is pivotal to achieving the business objectives of a system. At the business level, the collection of information stored in disparate data- bases and reorganized into a “data warehouse” enables data mining or knowledge discovery that can have an impact on the success of the business itself. In every case, data design plays an important role. Data design is discussed in more detail in Chapter 10.
CHAPTER 9 DESIGN CONCEPTS 175
9.4.3 Architectural Design Elements The architectural design for software is the equivalent to the floor plan of a house. The floor plan depicts the overall layout of the rooms; their size, shape, and relation- ship to one another; and the doors and windows that allow movement into and out of the rooms. The floor plan gives us an overall view of the house. Architectural design elements give us an overall view of the software.
The architectural model [Sha15] is derived from three sources: (1) information about the application domain for the software to be built, (2) specific requirements model elements such as use cases or analysis classes, their relationships, and col- laborations for the problem at hand, and (3) the availability of architectural styles (Chapter 10) and patterns (Chapter 14).
The architectural design element is usually depicted as a set of interconnected sub- systems, often derived from analysis packages within the requirements model. Each subsystem may have its own architecture (e.g., a graphical user interface might be structured according to a preexisting architectural style for user interfaces). Techniques for deriving specific elements of the architectural model are presented in Chapter 10.
9.4.4 Interface Design Elements The interface design for software is analogous to a set of detailed drawings (and specifications) for the doors, windows, and external utilities of a house. The detailed drawings (and specifications) for the doors, windows, and external utilities tell us how things and information flow into and out of the house and within the rooms that are part of the floor plan. The interface design elements for software depict information flows into and out of a system and how it is communicated among the components defined as part of the architecture.
There are three important elements of interface design: (1) the user interface (UI); (2) external interfaces; to other systems, devices, networks, or other producers or consumers of information; and (3) internal interfaces between various design compo- nents. These interface design elements allow the software to communicate externally and enable internal communication and collaboration among the components that populate the software architecture.
UI design (increasingly called UX or user experience design) is a major software engineering action and is considered in detail in Chapter 12. UX design focuses on ensuring the usability of the UI design. A usable design incorporates carefully chosen aesthetic elements (e.g., layout, color, graphics, information layout), ergonomic ele- ments (e.g., interaction mechanisms, information placement, metaphors, UI naviga- tion), and technical elements (e.g., UX patterns, reusable components). In general, the UI is a unique subsystem within the overall application architecture designed to pro- vide the end user with a satisfying user experience.
The design of external interfaces requires definitive information about the entity to which information is sent or received. In every case, this information should be collected during requirements engineering (Chapter 7) and verified once the interface design commences.10 The design of external interfaces should incorporate error check- ing and appropriate security features.
10 Interface characteristics can change with time. Therefore, a designer should ensure that the specification for the interface is accurate and complete.
176 PART TWO MODELING
The design of internal interfaces is closely aligned with component-level design (Chapter 11). Design realizations of analysis classes represent all operations and the messaging schemes required to enable communication and collaboration between operations in various classes. Each message must be designed to accommodate the requisite information transfer and the specific functional requirements of the operation that has been requested.
In some cases, an interface is modeled in much the same way as a class. An inter- face is a set of operations that describes some part of the behavior of a class and provides access to these operations.
For example, the SafeHome security function makes use of a control panel that allows a homeowner to control certain features of the security function. In an advanced version of the system, control panel functions may be implemented via a mobile platform (e.g., smartphone or tablet) and are represented in Figure 9.5.
9.4.5 Component-Level Design Elements The component-level design for software is the equivalent to a set of detailed drawings (and specifications) for each room in a house. These drawings depict wiring and plumbing within each room, the location of electrical receptacles and wall switches,
redKeystroke() decodeKey()
<<Interface>> KeyPad
LCDdisplay LEDindicators keyPadCharacteristics speaker wirelessInterface
readKeyStroke() decodeKey() displayStatus() lightLEDs() sendControlMsg()
ControlPanel
Tablet SmartPhone
KeyPad
Figure 9.5 Interface rep- resentation for ControlPanel
CHAPTER 9 DESIGN CONCEPTS 177
faucets, sinks, showers, tubs, drains, cabinets, and closets, and every other detail asso- ciated with a room.
The component-level design for software fully describes the internal detail of each software component. To accomplish this, the component-level design defines data structures for all local data objects and algorithmic detail for all processing that occurs within a component and an interface that allows access to all component operations (behaviors).
Within the context of object-oriented software engineering, a component is repre- sented in UML diagrammatic form, as shown in Figure 9.6. In this figure, a component named SensorManagement (part of the SafeHome security function) is represented. A dashed arrow connects the component to a class named Sensor that is assigned to it. The SensorManagement component performs all functions associated with Safe- Home sensors including monitoring and configuring them. Further discussion of com- ponent design is presented in Chapter 11.
The design details of a component can be modeled at many different levels of abstraction. A UML activity diagram can be used to represent processing logic. Algo- rithmic structure details for a component can be represented using either pseudocode (a programming languagelike representation described in Chapter 11) or some other diagrammatic form (e.g., flowchart). Data structure details are usually modeled using pseudocode or the programming language to be used for implementation.
9.4.6 Deployment-Level Design Elements Deployment-level design elements indicate how software functionality and subsystems will be allocated within the physical computing environment that will support the software. For example, the elements of the SafeHome product are configured to oper- ate within three primary computing environments—a mobile device—in this case a PC, the SafeHome control panel, and a server housed at CPI Corp. (providing Internet- based access to the system).
During design, a UML deployment diagram is developed and then refined, as shown in Figure 9.7. In the figure, three computing environments are shown (in the full design there would be more details included: sensors, cameras, and the functionality delivered by mobile platforms). The subsystems (functionality) housed within each computing element are indicated. For example, the personal computer houses subsys- tems that implement security, surveillance, home management, and communications features. In addition, an external access subsystem has been designed to manage all attempts to access the SafeHome system from an external source. Each subsystem would be elaborated to indicate the components that it implements.
SensorManagement Sensor
Figure 9.6 A UML component diagram
178 PART TWO MODELING
The diagram shown in Figure 9.7 is in descriptor form. This means that the deploy- ment diagram shows the computing environment but does not explicitly indicate con- figuration details. For example, the “personal computer” is not further identified. It could be a Mac, a Windows-based PC, a Linux box, or a mobile platform with its associated operating system. These details are provided when the deployment diagram is revisited in instance form during the latter stages of design or as construction begins. Each instance of the deployment (a specific, named hardware configuration) is identified.
9 .5 su m m a ry
Software design commences as the first iteration of requirements engineering con- cludes. The intent of software design is to apply a set of principles, concepts, and practices that lead to the development of a high-quality system or product. The goal of design is to create a model of software that will implement all customer requirements
Personal computer
Control panel CPI server
CommunicationHomeManagement
Security Surveillance
ExternalAccess
Security HomeownerAccess
Figure 9.7 A UML deployment diagram
CHAPTER 9 DESIGN CONCEPTS 179
correctly and bring delight to those who use it. Software designers must sift through many design alternatives and converge on a solution that best suits the needs of proj- ect stakeholders.
The design process moves from a “big picture” view of software to a narrower view that defines the detail required to implement a system. The process begins by focusing on architecture. Subsystems are defined, communication mechanisms among subsystems are established, components are identified, and a detailed description of each component is developed. In addition, external, internal, and user interfaces are designed at the same time.
Design concepts have evolved over the first 60 years of software engineering work. They describe attributes of computer software that should be present regardless of the software engineering process that is chosen, the design methods that are applied, or the programming languages that are used. In essence, design concepts emphasize the need for abstraction as a mechanism for creating reusable software components; the importance of architecture as a way to better understand the overall structure of a system; the benefits of pattern-based engineering as a technique for designing software with proven capabilities; the value of separation of concerns and effective modularity as a way to make software more understandable, more testable, and more maintain- able; the consequences of information hiding as a mechanism for reducing the propa- gation of side effects when errors do occur; the impact of functional independence as a criterion for building effective modules; the use of refinement as a design mecha- nism; the application of refactoring for optimizing the design that is derived; the importance of object-oriented classes and the characteristics that are related to them; the need to use abstraction to reduce coupling between components; and the impor- tance of design for testing.
The design model encompasses four different elements. As each of these elements is developed, a more complete view of the design evolves. The architectural element uses information derived from the application domain, the requirements model, and available catalogs for patterns and styles to derive a complete structural representation of the software, its subsystems, and components. Interface design elements model external and internal interfaces and the user interface. Component-level elements define each of the modules (components) that populate the architecture. Finally, deployment-level design elements allocate the architecture, its components, and the interfaces to the physical configuration that will house the software.
pro b L e m s a n D po i n t s to po n D e r
9.1. Do you design software when you “write” a program? What makes software design dif- ferent from coding?
9.2. If a software design is not a program (and it isn’t), then what is it?
9.3. How do we assess the quality of a software design?
9.4. Describe software architecture in your own words.
9.5. Describe separation of concerns in your own words. Is there a case when a “divide and conquer” strategy may not be appropriate? How might such a case affect the argument for modularity?
180 PART TWO MODELING
9.6. Discuss the relationship between the concept of information hiding as an attribute of effective modularity and the concept of module independence.
9.7. How are the concepts of coupling and software portability related? Provide examples to support your discussion.
9.8. Apply a “stepwise refinement approach” to develop three different levels of procedural abstractions for one or more of the following programs: (1) Develop a check writer that, given a numeric dollar amount, will print the amount in words normally required on a check. (2) Iteratively solve for the roots of a transcendental equation. (3) Develop a simple task- scheduling algorithm for an operating system.
9.9. Does refactoring mean that you modify the entire design iteratively? If not, what does it mean?
9.10. Briefly describe each of the four elements of the design model.
Design element: Quick Look icon magnifying glass: © Roger Pressman
