This is part of the supporting material from our first book, Applied Software Project Management, which was published by O’Reilly in 2005. You can see all of the material here: https://www.stellman-greene.com/applied-software-project-management/
- 1 Inspections
- 2 Deskchecks
- 3 Walkthroughs
- 4 Code Reviews
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 which an inspector disagrees with.
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 them 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.)
|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 product being inspected
|Entry Criteria||A moderator must be selected, as well as team of three to ten people. A work product must be selected, and each team member has read it individually and identified all wording which 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||
|Exit Criteria||The work product has been approved.|
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, 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.
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.
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 which 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 which will be inserted into the document in order to fix the defect; the moderator should add this fix should 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 they 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.
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.
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 cannot be resolved or additional defects which 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.
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
Inspections in Outsourced Projects
Reviews in outsourced projects can be highly time-consuming; much more so, in fact, than in an in-house project. In an in-house project, the team is already familiar with that particular organization’s standards, and there are usually plenty of examples to work from. The project manager doesn’t need to spend nearly as much time making sure that the team understands the work being accomplished. What’s more, an in-house team normally understands the mission of the organization and the needs of its users. Many project managers take this for granted, and don’t think to communicate these things to the vendor. It requires constant effort and vigilance on the part of the project manager to make sure that the needs are properly understood when moving work outside the organization. In addition to knowledge transfer, reviews are also important tools for collaboration. It is important to encourage collaboration between the project team members at the vendor and the team members within the organization. When an inspection team is made up of people from both organizations, the only way for them to reach consensus on a work product in order to approve it is to collaborate on identifying and fixing the defects in that work product. After the inspection, everyone has a better understanding of the work to be done, as well as of how everyone else thinks about that work.
The script below is an inspection process that has been modified to be used with an outsourced project. This script differs from the normal inspection process in that it does not require an inspection meeting. Instead, the inspectors prepare comments and send them back to the moderator, who consolidates them and works with individual inspectors to identify solutions that they all agree on. This requires much more time than a single inspection meeting because, instead of having one single discussion about each defect, the moderator must have many different discussions with individual inspectors regarding each defect. It also requires that the moderator who is selected have extensive familiarity and expertise with the work product being inspected. This may mean that the project manager must serve as the moderator, but that’s not always the case.
|Name||Inspection script for use in multiple organizations|
|Purpose||To run a moderated inspection (without a meeting) for a team with members in different organizations|
|Summary||In an inspection, a moderator leads a team of reviewers in reviewing a work product and fixing any defects that are found. The inspectors are in multiple organizations, so they never meet face to face.|
Work product being inspected
|Entry Criteria||A moderator must be selected, as well as team of three to ten people. A work product must be selected, and each team member has read it individually and identified all wording which must be changed or clarified before he or she will approve the work product.|
|Basic Course of Events||
|Exit Criteria||The work product has been approved.|
A deskcheck is a simple review in which the author of a work product distributes it to one or more reviewers. In a deskcheck, the author sends a copy of the work product to selected project team members. The team members read it, and then write up defects and comments to send back to the author. Unlike an inspection, a deskcheck does not produce written logs which can be archived with the document for later reference. There is no follow-up meeting or approval process. It is simply a way for one team member to check another’s work. Deskchecks are not formal reviews (where “formal” simply means that it generates a written work product which meets a certain standard and is archived with the rest of the project documentation); there is no standard for the results of the deskcheck. The reviewers simply review the work product and return the results. There is no moderator, and there is not necessarily any consensus generated.
There are times when a full inspection is neither necessary nor useful. Some work products do not benefit enough to warrant the attention of an entire inspection team because they do not need consensus or approval. In these cases, the author simply needs input from others to prevent defects, but does not require that they approve the document. In these cases, the deskcheck is a useful review practice.
The illustration below contains an example of comments from a deskcheck which was used by a tester to find defects in an automation script. In this case, the entire review was performed via e-mail: the author mailed the script to the reviewer, and the reviewer read it and e-mailed the comments back to the author. These comments are much simpler than the inspection log in Figure 5-1. In an inspection, each log entry must either resolve a defect or indicate that it is an open issue which must be resolved. Deskcheck comments can simply point out issues or raise questions without having to supply solutions or promise a resolution. There was no follow-up or approval, and the reviewer had no more contact with this script.
A walkthrough is an informal way of presenting a technical document in a meeting. Unlike other kinds of reviews, the author runs the walkthrough: calling the meeting, inviting the reviewers, soliciting comments and ensuring that everyone present understands the work product. It typically does not follow a rigid procedure; rather, the author presents the work product to the audience in a manner that makes sense. Many walkthroughs present the document using a slide presentation, where each section of a work product is shown using a set of slides. Work products that are commonly reviewed using a walkthrough include design specifications and use cases.
Wakthroughs are used when the author of a work product needs to take into account the perspective of someone who does not have the technical expertise to review the document. For example, a requirements analyst must make sure that the use cases she builds will provide the functionality that the users need, but the user representatives may not have seen use cases before and would be overwhelmed by them. If these users are simply included as part of an inspection team, it is likely that they will read the document and, failing to find many defects, sit silently through the inspection meeting without contributing much. This is not their fault—their training is in the business of the organization, not in reading and understanding software engineering documents. This is where a walkthrough can be a useful technique to ensure that everyone understands the document.
Before the walkthrough, the author should distribute any material that will be presented to each person who will be attending. For example, if the walkthrough is done as a slide presentation, copies of the slides should be e-mailed to the attendees. If only a portion of that material is going to be covered, that should be indicated as well.
During the walkthrough meeting, the author should solicit feedback from the audience. This is an opportunity to brainstorm new or alternative ideas, and to check that each person understands the document that is being presented. The author should go through parts of the document to make sure that it was presented in as clear a manner as possible.
These guidelines can help an author lead a successful walkthrough meeting:
- Verify that everyone is present who needs to review the work product. This could include users, stakeholders, engineering leads, managers and other interested people.
- Verify that everyone present understands the purpose of the walkthrough meeting, and how the material is going to be presented.
- Describe each section of the material to be covered by the walkthrough.
- Present the material in each section, ensuring that everyone present understands the material being presented.
- Lead discussion to identify missing any sections or material.
- Document all issues that are raised by walkthrough attendees.
After the meeting, the author should follow up with individual attendees who may have had additional information or insights. The document should then be corrected to reflect any issues that were raised.
Select the Code Sample
The first task in a code review is to select the sample of code to be inspected. It’s impossible to review every line of code, so the programmers need to be selective about which portion of the code gets reviewed. Many teams have found that it takes about two hours to review 400 lines of code (in a high-level language such as Java), although this estimate differs dramatically from team to team and depends on the complexity of the code being reviewed. At that rate, there is no way a team could review all of the code for a software project. Nor would the team want to—in any program, there is a good deal of uninteresting code that looks very similar to the code already developed in previous applications, which has a lower risk of containing as many defects.
Hold the Review Session
The team selection and preparation in a code review are similar to any other kind of inspection. An inspection team of three to ten people must be selected. Each of these people must be technically capable of reading and understanding the code being reviewed. Before the meeting the moderator distributes the code sample to each inspector, who does individual preparation exactly as in the inspection.
The main difference between a code review and any other kind of inspection is in the review session. While code review session is similar to the inspection meeting (see “Page-by-page review” above), there are a few important differences:
- One important difference is that in addition to the moderator, there is a code reader who reads the code aloud during the meeting. The purpose of the reader is simply to keep the team’s place during the inspection; the team should have already read the code and identified defects during their preparation.
- Another important difference between code reviews and document inspections is that the code review is much more focused on detecting defects, and less on fixing them.
- In the code review, the moderator needs to be especially careful not to let the meeting turn into a problem-solving session. Programmers love to solve problems. It’s easy for them to get caught up in a small detail and turn the meeting into an analysis of a minute problem that covers just a few lines of code.
The following attributes should be verified during a code review:
- Is the code clear and easy to understand?
- Did the programmer unnecessarily obfuscate any part of it?
- Can the code be refactored to make it clearer?
- Will other programmers be able to maintain this code?
- Is it well-commented and documented properly?
- Does the code accomplish what it is meant to do?
- If an algorithm is being implemented, is it implemented correctly?
Reliability and Robustness
- Is the code fault-tolerant? Is it error-tolerant?
- Will it handle abnormal conditions or malformed input?
- Does it fail gracefully if it encounters an unexpected condition?
- Is the code vulnerable to unauthorized access or malicious use or modification?
- Could the code be a bottleneck that prevents the system from growing to accommodate increased load, data, users or input?
- Could this code be reused in other applications?
- Can it be made more general?
- Does the code make efficient use of memory, CPU cycles, bandwidth or other system resources?
- Can it be optimized?