Section 5.1. Inspections


5.1. Inspections

An inspection is one of the most common sorts of review found in software projects. The goal of the inspection is for all of the inspectors to reach consensus on a work product and approve it for use in the project. Commonly inspected work products include software requirements specifications (see Chapter 6) and test plans (see Chapter 8). In an inspection, a work product is selected for review and a team is gathered for an inspection meeting to review the work product. A moderator is chosen to moderate the meeting. Each inspector prepares for the meeting by reading the work product and noting each defect. In an inspection, a defect is any part of the work product that will keep an inspector from approving it. For example, if the team is inspecting a software requirements specification, each defect will be text in the document that an inspector disagrees with. The goal of the inspection is to repair all of the defects so that everyone on the inspection team can approve the work product.

Most project managers have seen their projects get delayed because of scope creep and unnecessary work caused by changes that, had they been caught earlier, would have required much less work to fix. One of the most common complaints from project team members is that they would have built the software differently had they been given a better understanding of what was needed from the beginning. One important root cause of these problems is defects in work products that are not caught until long after those work products have been used as the basis for later project activities.

The most important reason to inspect documents is to prevent defects. If the team starts building software based on a vision and scope document that has a serious defect, eventually the entire project will have to stop and reverse course. This can be very expensive in both effort and morale, because the team will need to backtrack and revise the requirements, design, code, test plans, and other work products that they have already put a lot of effort into implementing. The same goes for defects that were caught in other work productsdefects missed in a design specification, for example, will have to be corrected later after they have been coded. The longer a defect goes uncorrected, the more entrenched it is in other work products; the more entrenched it is, the more time and effort it will take to fix.

According to a report by the Software Engineering Institute, it costs more to not do inspections than it does to do them. A national survey of software engineering teams found that in a typical inspection, four to five people spend one to two hours preparing for inspections, followed by one to two hours to hold an inspection meeting. The total effort required for the inspection, therefore, is 10 to 20 person-hours; this effort results in the early detection of an average of 5 to 10 defects. (On the average, these defects, if left in the document, would require either 250 to 500 lines of new code or modification of 1000 to 1500 lines of legacy code to repair if they were eventually caughtwhich would almost certainly require well over 20 person-hours of programmers' time!) This is a very high return on investment; few tools, techniques, or practices are as effective as inspections for increasing the quality of the software.

Inspections are easy to implement, and have an immediate effect on quality and consensus-building. A small team spending a few hours inspecting a work product will catch errors that could potentially save weeks, or even months, of wasted effort. An effective inspection requires a well-chosen team, a moderator who is able to run the meeting, and an author who is willing to listen to criticism and fix the work product being inspected.

5.1.1. Choose the Inspection Team

The job of the inspection team is to work with the author of the document in order to identify any defects. A defect is any problem in the document that will prevent an inspector from approving it. Once a problem is identified, the inspection team must work to come up with a solution that will fix the problem. When the team meets to inspect the document, they will be expected to come up with solutions to the defects that they find. The project manager must select a team that can perform this function. This means that each inspector needs to have enough familiarity with the project and the way the work product will be used to understand its problems and propose changes. (Team members who use the document in their day-to-day work should have no problem with this.)

The project manager must choose a team of 3 to 10 inspectors. Ideally, each inspector should represent a different perspective on the work product. A designer will use a document for different tasks than a programmer will. It is important that each person who will use the document has his views represented in the inspection team. This is critical for catching all of the defects.

During the inspection, the team works to identify any defects in the work product. They are expected to evaluate it from two perspectives. The most important evaluation is from the perspective of their own expertise, where the inspectors identify any issues that will interfere with the development of the project. For this role, they must draw on their engineering skills and experience with past software projects. But inspectors should also evaluate the work product from a common sense perspective. Each inspection team member should think about the ideas in the vision and scope document and consider several questions: does the work product being inspected fulfill the needs laid out in the vision and scope document? Does it really answer the problem posed by earlier work products? Will it be able to serve as a basis for all of the work products that will come later in the product? Good inspection team members will be able to keep these questions in mind.

5.1.2. Select a Moderator

The project manager must choose a moderator to run the inspection meetings. This person must be able to objectively evaluate the work product being inspected and understand any issues that are raised during the inspection. The moderator will also need to be able to control the meeting. If a few inspectors start a discussion to address a defect that might take a lot of time, the moderator will have to be able to stop that discussion and table it as an open issue. It takes some practice to keep control of a meeting.

The project manager should be an inspector, so an independent and unbiased moderator is needed. A good moderator will have sufficient technical background to understand the work product being inspected. It is important for the moderator to be objective, and not to favor one perspective over another during the inspection meeting. In some organizations, the moderator is never a part of the project team, and does not have a stake in the project. However, some people have found it useful to select as moderator a team member who will not be inspecting the document, because the moderator should have an understanding of the issues discussed during the meeting. But in that case, that team member must be willing and able to stay objective by allowing every inspector equal opportunity to bring up defects, and by ensuring that each issue is discussed and either resolved or tagged as an open issue.

The hardest part of the moderator's job is to prepare the inspectors and the author for criticism of the work product. When somebody writes a document, he may be uncomfortable with the idea that it contains errors. It's his work and, in our day-to-day lives, few of us are used to having our work critiqued. But all documents have defects, and authors need to get comfortable with this idea. This is by far the most challenging part of implementing inspections: getting people comfortable with having their work criticized.

To address this, the moderator must help the author understand the benefit of the criticism. It's the moderator's job to make sure that the meeting does not become personal criticism, and that the comments are always constructive. An effective way to do this is to focus the discussion on each defect and come up with a specific resolution. It's the job of the inspection team to do more than just identify the problems; they must also come up with the solutions. The moderator compiles all of the defect resolutions into an inspection log (see Figure 5-1 for an example).

Figure 5-1. Sample inspection log


At the top of each inspection log is information about the inspection meeting: what work product was being reviewed, when it was held, who was in attendance, whether or not the work product was read by each inspector, how long each inspector spent reviewing the work product, and how many issues (including both defects and open issues) were found. Each work product should have a unique version number, to ensure that the inspection log can be matched up to the proper version of the work product.

The inspection moderator should ask each team member how long he or she spent reviewing the work product and record that number in the log. This stands as a record of how much effort went into the work product, which will help in future estimation, project planning, and impact analysis activities. If any inspector failed to review the work product, the moderator must halt the meeting and reschedule it in order to allow all of the inspectors enough time to review the work product.

The rest of the inspection log contains a list of action items. Each item is marked with the exact location of the defect and the solution proposed by the inspection team. In many cases, the solution is a wording change. The work product contains a specific sentence that is unclear, ambiguous, or incorrect. After a brief (usually under five minutes) discussion, the inspection team identifies wording that will correct the defect. In this case, the moderator writes the new wording in the inspection log, and the author agrees to update the work product accordingly.

In other cases, the solution is too complex to be identified at the inspection meeting . If the discussion lasts too long, the moderator should stop it and add an open issue to the inspection log. This issue must be assigned to the author and, optionally, one or more inspection team members; it is their responsibility to resolve the issue. The log item for this must contain a specific set of actions to be performed ("meet with Marketing to research this missing feature," "rewrite lines 534 through 539 so system will perform data check on report B").

It is important that the inspection log is readily available to all inspectors. After the meeting, it should be distributed to all inspectors, and stored along with previous versions of the document. If the document is checked into a version control system (see Chapter 7), then each inspection log should be checked in along with it. All changes must be made before the work product can be inspected again: open issues must be closed, defects must be repaired, and every issue reported in the log must be addressed.

5.1.3. Inspect the Work Product

During the inspection meeting, a moderator leads the team page by page through a printed copy of the work product. The purpose of the meeting is to identify and fix any defects. The moderator does not actually read each page out loud or give the team time to read the page. The team members read the document prior to the inspection, during their preparation. When the moderator goes through the document page by page, he simply asks the reviewers for their defects on page 1; once those are done, he asks for the defects on page 2 and continues through the rest of the document.

Prior to the inspection meeting, each team member should be given a checklist to help her identify defects. Checklists will be different for different kinds of work products. (In other chapters, checklists will be included for each type of work product that should be inspected.) The script in Table 5-1 describes the process for an inspection meeting.

Table 5-1. Inspection meeting script

Name

Inspection meeting script

Purpose

To run a moderated inspection meeting

Summary

In an inspection meeting, a moderator leads a team of reviewers in reviewing a work product and fixing any defects that are found.

Work Products


Input

Work product being inspected


Output

Inspection log

Entry Criteria

A moderator must be selected, as well as team of 3 to 10 people. A work product must be selected, and each team member has read it individually and identified all wording that must be changed or clarified before he or she will approve the work product. A unique version number has been assigned to the work product.

Basic Course of Events

  1. Preparation. The moderator distributes a printed version of the work product (with line numbers) to each inspector, along with a checklist to aid in the review. Each inspector reads the work product and identifies any defects to be brought up at the meeting.

  2. Overview. The inspection meeting begins. The moderator verifies that each team member is prepared.

  3. Page-by-page review. The moderator runs through the work product page by page. Inspectors indicate where there are defects. Each defect is either resolved or left as an open issue. The moderator adds each defect to the inspection log.

  4. Rework. The author repairs the defects identified in the inspection meeting.

  5. Follow-up. Inspection team members verify that the defects were repaired.

  6. Approval. The inspection team approves the work product.

Alternative Paths

  1. During Step 2, if any team member has not read the work product, then the inspection is halted. The meeting is rescheduled and the script returns to step 1.

  2. During Step 4, if an inspection team member discovers additional defects in the work product, then the moderator calls another meeting and the process returns to step 1.

Exit Criteria

The work product has been approved.



Preparation

Each inspector reviews the printed copy of the work product individually, prior to the inspection meeting. Any defects that are found should be marked on the copy so that they can be brought up in the meeting.

In many organizations, the moderator requires that each inspector submit a written list of defects that were found prior to the inspection meeting, and all defects are compiled into a single inspection log and distributed to the entire inspection team. This optional step can reduce the time required for the meeting because instead of going through the entire work product page by page, the moderator only goes through the log, and the author and inspectors have time to prepare in advance to respond to the defects.


Overview

The moderator verifies that each inspection team member has read the printed copy of the work product. If any team member has not prepared, the inspection is aborted and rescheduled for a later date.


Page-by-page review

The moderator turns to the first page of the work product and asks if anyone found any issues on that page. Team members bring up each issue that they found during their preparation. For each issue, the moderator leads a discussion between the team and the author to identify new wording that will resolve the issue. (For work products that are not text or documents, the team describes the change in sufficient detail so that the repair of the defect is unambiguous to the author.) The team should come up with the actual text that will be inserted into the document in order to fix the defect; the moderator should add this fix to the inspection log. If the team cannot come up with a fix on the spot, or if discussion lasts more than about five minutes, the moderator adds it to the inspection log as an open issue and assigns it to the team member who brought it up (and anyone else who is involved), so he can work with the author to resolve it. Once all issues for the page are discussed, the moderator moves to the next page in the work product.


Rework

After the inspection meeting is over, the author makes the changes in the inspection log and works with the inspection team members to resolve all open issues. When the changes are complete, the author turns the updated work product over to the moderator.


Follow-up

The moderator distributes the updated work product to the inspection team. Each team member verifies that he can now approve the work product. If there are any issues that were not fully resolved or additional defects that were not caught, he notifies the moderator, who calls another inspection meeting and starts the inspection process over again. Once the team gets through an inspection without any open issues and can agree on any changes that must be made, the work product can be updated and distributed for approval.


Approval

If any inspector feels that there are still further issues raised by the corrections to the work product, another inspection meeting can be held; however, the project manager and author can also work individually with everyone involved to make sure that the changes are adequate. Once everyone on the team feels that the changes they identified are adequate, they can approve the updated work product without holding another inspection meeting.

The moderator adds a signature page to the work product and distributes a printed version for signature approval. The signed work product is archived.

5.1.4. Manage the Author's Expectations

Many people who have implemented inspections have found that it is very difficult for authors to sit through an inspection meeting without defending their work. Instead of providing clarification that is used to update the work product, they take over the discussion and, by being defensive and loud, get the inspectors to agree not to report defects. This is counterproductive: it leads to situations when the inspection team understands what the author meant, but the work product, which remains unchanged, does not reflect this. It is the moderator's job to keep the discussions on track and prepare the authors for the inspection.

A major challenge of the moderator role is keeping the author from altering the understanding of the document through discussion. The purpose of the discussions is not to teach the inspectors about the project; it is to change the document so that the author and all of the inspectors will approve it. There is a simple rule in document inspection: if there is a misunderstanding about words in the document, they need to be clarified in the document, and not just in the minds of the people who happened to attend the inspection meeting.

Each inspector should keep in mind the fact that if he did not understand something after reading a document, then it is probably the document's fault, not the reader's. If he did not understand it, then it is likely that another reader will also have the same problem (especially considering that most software documents will be used as reference later, by people who are less familiar with the project than the inspectors). For this reason, it is very important that inspectors make it clear when they do not understand something. This is difficult for many inspectors: it's hard for people to admit that they did not understand something that they have read. It is the moderator's job to draw these misunderstandings out of the inspectors during the discussions of each defect.

The author should be prepared to listen to the inspection team discuss defects. It is tempting to get defensive and try to defend each defect. The author must remember that if someone thinks that an issue is worth bringing up in the meeting, there may be some ambiguity there, no matter how clear it seems to the person who wrote the words.

One way to help the author feel less defensive is to take the option (described above, under "Preparation") in which the inspection team members submit their defects to the moderator before the inspection meeting. The moderator compiles all of the defects into a log, which is then sent back to the inspection team. This is helpful because it gives the author advance warning of all of the defects that will be discussed. It also allows the inspection team to prepare solutions to the defects in advance. However, it requires more effort on the part of the moderator, who has to look through all of the defects up front in order to group redundant defects together and make sure that each one is described clearly.

In some organizations, project managers have found it useful to require that the authors not talk in the inspection meetings, to let the document stand on its own. In others, the author is excluded from the meeting entirely, and is simply given the inspection log. Although this sounds drastic and impersonal to some people, some moderators have found this to be a very useful practice, as the team feels that they must put a lot of effort into making the inspection log as self-explanatory as possible. However, while these practices do prevent the author from skewing the results of the inspection, they also cause the author to miss out on important discussions; this is a costly trade-off. As long as the author is able to listen to the moderator's rules, especially when it comes to identifying and addressing defects, he can be a valuable participant in the inspection process.

5.1.5. Help Others in the Organization Accept Inspections

Over the many years that inspections have been practiced in software organizations, project managers have often found that when they attempt to implement inspections, the team pushes back. This opposition occurs because, to some people, it is not intuitively obvious that spending the time inspecting the work products up front will save the team from having to fix the software later. The project manager should prepare for potential resistance by understanding exactly why inspections are important.

Project managers often find that engineers are very unhappy with the idea of inspections. To some, inspections seem unnecessarily "bureaucratic." This is especially unfortunate because inspections are one of the most effective ways to prevent defects and make the most efficient use of the engineers' time. There are few tools or techniques that have such a high potential savings in effort. For each hour spent inspecting documents, the team saves many hours that would otherwise be lost on correcting problems that would have been coded incorrectlypreventing the very tasks that engineers find most frustrating.

Luckily, a small number of objections tend to be raised most of the time, and each of these objections has a straightforward response. In the end, it is usually not hard for a project manager to show most reasonable people that inspections are worth doing.

The most effective way a project manager can sell inspections to the organization is to show the savings in terms of time and money. Each inspection yields defects that would have been much more expensive to fix had they not been found; it should not be hard to give a rough idea of just how much time and money would have been wasted on those defects.

Another way the project manager can sell inspections is by pointing out the knowledge transfer benefits. By instituting inspections and code reviews, engineers other than the author of a work product are cross-trained on it, and can maintain it in the future if the author is busy with another project or has left the organization. Another way a project manager can help people accept inspections and understand their benefit is to run the first inspection meetings using work products created by people who are widely respected in the organization. Once others see the inspections run well and respectfully, they will be much more likely to accept the same practice applied to their own work.

When a project manager starts working toward implementing inspections, there are three objections that come up most often: people feel that inspections take too long, they do not like their work criticized, and they are protective of the final product. Luckily, it is not hard to anticipate these objections and give effective responses. (See Chapter 9 for more advice on making changes in an organization.)

5.1.5.1. "Inspections take too long."

Some team members seem to be opposed to anything that seems "bureaucratic." To them, inspections are just paper-shuffling meetings that waste their time. They should be writing code (or design specifications, test plans, requirements, etc.), and don't have time to waste just so some manager can check some box somewhere.

To convince someone with this mindset that inspections are necessary, the project manager must show him that every minute spent doing inspections can save many more down the road. Over the years, software engineering researchers have studied thousands of software projects in many different kinds of organizations. They have found again and again that a defect that takes a few minutes to fix in a vision and scope or a use case document will require hours, days, or weeks to fix in code or testing.

The project manager should explain that a typical inspection meeting will take less than two hours. If each person at the meeting finds a single defect, it more than makes up for the time that he spent reading and correcting the document. When looked at from this perspective, doing the inspection saves time.

5.1.5.2. "I don't like people criticizing my work."

Many people are uncomfortable putting their work up for review. They are unsure of their documents, and they are not used to having people point out their mistakes. It is very important to recognize this, because it often falls on the project manager to help the team members get comfortable with having their work put under a magnifying glass.

When this objection is raised, the project manager can point out that everyone makes mistakes, and that usually those mistakes are not the fault of the author. Frequently, when there is a problem in a document, it is because the author did not have enough information: bringing in the rest of the team can fill in those gaps.

The project manager can also point out that while it may be uncomfortable to have mistakes pointed out during the inspection, it's much more uncomfortable when those mistakes are left in the document. The author of a use case document may feel bad momentarily when defects are pointed out and corrected during an inspection meeting. But if he feels bad then, he will feel terrible if those defects are not caught until after the team spends months designing, programming, and testing the software, only to discover a "bug" that turns out to be a problem in his use case document. Instead of feeling bad when the inspection team points out problems, he should feel relieved that they were caught before they could cause project delays.

Defects should be discussed in terms of what is best for the work product or the project, not as criticisms of the author. It is very important that the moderator be extremely strict during the inspection meetings toward people who make rude personal comments. The moderator should enforce professionalism, and should ensure that every inspection meeting is conducted in a positive manner.

5.1.5.3. "I built it, and only I can say when it's done."

Some people are very protective of their work, and simply don't want other people to criticize it. In these cases, the author feels that she is the expert, and feels that there's nobody else in the organization who knows more about this subject than she does. Be very careful when confronting herthis is an emotionally charged situation, and it's very easy to turn this person off permanently. It is important for the project manager to be nonconfrontational. The project manager should work to influence this person, not to force her into a situation she doesn't want to participate in.

The best argument in this situation is to show her that the inspection is a tool that is there for her to use. It is like a spellcheck in a word processor: the document is always better after the spellcheck.

Nobody, no matter how good he is at his job, can deliver a perfect document. It is impossible to know exactly what's in the heads of the intended readers. There is no way to include the entire context in a document. There will always be technical or organizational concepts that would take pages and pages to explain, but that everyone is familiar with. For example, a use case document for accounting software will not explain how double-entry accounting works; it will assume that every reader is familiar with the concept.

When an inspector finds a defect, he is helping the author identify areas that need to be explained. The author assumed that each reader fully understood a concept: it turned out that the reader needed some clarification after all. In this way, the document can be adjusted to the level of its specific readers.

The hesitant author will generally recognize that she has expertise that her readers do not have. Explain that while she can make an educated guess at what context and background needs to be included, she has no way of knowing if it is enough. The inspection process is an efficient technique to help her fix this.


Note: More information on inspections can be found in Software Inspection by Tom Gilb and Dorothy Graham (Addison Wesley, 1993) and Peer Reviews in Software by Karl Wiegers (Addison Wesley, 2002). Information on the effectiveness of software inspections can be found in the Software Technology Roadmap: http://www.sei.cmu.edu/str/.


Applied Software Project Management
Applied Software Project Management
ISBN: 0596009488
EAN: 2147483647
Year: 2003
Pages: 122

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net