Applied Software Project Management – Review Practices

Tools

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/

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 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 Products Input
Work product being inspected
Output
Inspection log
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
  1. Preparation. The moderator distributes 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, 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 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.

Sample Inspection Log
Sample Inspection Log

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

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 Products Input
Work product being inspected
Output
Inspection log
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
  1. Preparation. The moderator distributes a printed or electronic 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 that must be resolved, compiles those defects into a single document, and returns it to the moderator.
  2. Compile the draft inspection log. Each list of defects returned by each inspector must be compared with the others, in order to identify and combine overlapping defects. The moderator compiles a draft of the inspection log that includes all distinct defects found by inspectors. The log does not yet contain any solutions to those defects.
  3. Identify conflicts. The moderator searches for any defects reported by different inspectors which contradict each other. For each set of conflicting defects, the moderator holds a discussion (either in person or via teleconference or video conference, or using a collaboration tool like a mailing list or instant message system) between the inspectors who identified those defects, in order to identify the assumptions behind the defects and resolve them into a single defect. The inspection log is updated to reflect the combined defects.
  4. Identify solutions. The moderator uses the same means to meet with individual inspectors to identify solutions to the defects and add those solutions to the inspection log. If more than one person identified the same defect, they must all be involved in creating the solution. Inspectors may also identify additional defects which were not originally found, as well as their solutions.
  5. Compile and distribute inspection log. The moderator compiles all solutions identified in Step 4 into the inspection log. Any defects which were not resolved are left as open issues to be resolved by the author. The moderator sends the final inspection log to all inspectors for confirmation. When the inspectors have confirmed that the log is correct, it is sent to the author of the work product.
  6. Rework. The author repairs the defects identified in the inspection meeting.
  7. Follow-up. Inspection team members verify that the defects were repaired.
  8. Approval. The inspection team approves the work product.
 Alternative Paths
  1. During step 5, if one or more team members find errors in the inspection log, the moderator must address those errors before rework can occur. The script returns to step 2.
 Exit Criteria  The work product has been approved.

Deskchecks

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.

 

Sample Deskcheck Comments
Sample Deskcheck Comments

 

Deskchecks can be used as predecessors to inspections. In many cases, having an author of a work product pass his work to a peer for an informal review will significantly reduce the amount of effort involved in the inspection. Many defects can be caught by a single person reviewing a document. Approval and consensus is built later on during the inspection meeting; this is simply a way of saving effort. After a deskcheck, many authors will feel much more comfortable sending their document into an inspection—it will often help the author to be more objective and to take the inspection comments less personally.

Walkthroughs

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.

Code Reviews

A code review is a special kind of inspection in which the team examines a sample of code and fixes any defects in it. In a code review, a defect is a block of code which does not properly implement its requirements, which does not function as the programmer intended, or which is not incorrect but could be improved (for example, it could be made more readable or its performance could be improved). In addition to helping teams find and fix bugs, code reviews are useful for both cross-training programmers on the code being reviewed and for helping junior developers learn new programming techniques.

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.

Code Review Checklist

The following attributes should be verified during a code review:

Clarity

  • 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?

Maintainability

  • Will other programmers be able to maintain this code?
  • Is it well-commented and documented properly?

Accuracy

  • 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?

Security

  • Is the code vulnerable to unauthorized access or malicious use or modification?

Scalability

  • Could the code be a bottleneck that prevents the system from growing to accommodate increased load, data, users or input?

Reusability

  • Could this code be reused in other applications?
  • Can it be made more general?

Efficiency

  • Does the code make efficient use of memory, CPU cycles, bandwidth or other system resources?
  • Can it be optimized?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.