Integrated Solutions

Design Review Process

THIS DOCUMENT IS TO BE REGARDED AS THE OFFICial DESIGN REVIEW PROCESS within INTEGRATED SOLUTIONS. IT IS TO BE MAINTAINED UNDER CHANGE CONTROL BY the DOCUMENT CONTROL COORDINATOR.

Table of Contents

CHANGE SHEET

1.0 Introduction

2.0 The Review Process Overview

2.1 Entrance Criteria

2.2 The Meeting

2.3 Exit Criteria

2.4 Defect Ratings

2.5 Metrics

3.0 Configuration of the Review

4.0 The Role of the Author

4.1 Entrance Criteria

4.2 The Meeting

4.3 Exit Criteria

5.0 The Role of the Reviewer

5.1 Reviewer’s Checklist

5.2 Entrance Criteria

5.3 The Meeting

5.4 Exit Criteria

6.0 The Role of the Facilitator

6.1 Entrance Criteria

6.2 The Meeting

6.3 Exit Criteria

Additional References

Appendix A: Design Review Worksheet

1.0 Introduction

This document is the Design Review Process by which design reviews shall be conducted. Studies have shown that such discussions are an essential part of software development as they lead to a better product in a shorter time.

This process is was developed by Integrated Solutions, Code Inspection Process[1]. Also consulted for this paper was Best Area Practice: Requirements Software Inspections[2] and Fagan Defect-Free Process[3].

Design Reviews will be done on all major design efforts. The CEO/President or customer will decide on when they must be done. When they are required, this process must be followed.

2.0 The Review Process Overview

The design review process is a step that occurs before coding. The design is either a High-Level Software Design Specification, a Detailed Software Design Specification, or a combination of the two. The objective of a design review is to make sure that the design is taking the right approach. That is, the design meets the project requirements, and the design is one that will provide customer satisfaction.

The review should not be considered a time consuming event that must tackle all the defects found. Rather, it should be a simple process of systematically going through the design and listing areas of concern. Each area will be rated.

2.1 Entrance Criteria

• Author(s) has made the design ready for review. (See section The Role of the Author.)
• Reviewers have prepared for the review. (See section The Role of the Reviewer.)

The author(s) and reviewers must have completed their entrance criteria in order for the session to proceed smoothly and productively.

2.2 The Meeting

The meeting is scheduled well in advance so as to allow all parties to adequately prepare and meet their entrance criteria. The author is present as the author has a vested interest in ensuring that the review finds all possible defects and that the product meets exit criteria without ambiguity. The reviewers will take turns going through the design from start to finish. One of the reviewers will be designated the scribe, who records all issues and their conclusions. A facilitator will be present to ensure review guidelines are kept.

The meeting takes just two hours! If the design cannot be reviewed in two hours, then it must be broken up so that it can. At the very least, a long break should take place after two hours.

Remember that the reviewing takes place, for the most part, during the pre-meeting phase. The meeting should come as close to a listing of problem areas as can be maintained.

• All new design has been walked through.
• All issues have been raised and documented.

The author will revise the design based upon the documented feedback and will conduct another review if there are any Major Technical(MT) defects.

The review process is an important step not to be taken lightly. For the design is what begins to strictly define the future of the product. All discovered issues are taken outside the review arena to save time by consulting only with the person(s) necessary to solve them. Quite frequently, problems arise that are related to each other. These can then be grouped and thus handled more appropriately.

Once the review process is complete, the design is ready for coding.

2.4 Defect Ratings

These ratings are to be used by the scribe when noting issues as they arise during the meeting:

If the problem found is a Minor Change(MC), discussion of the solution may commence. However, if there exists a Major Technical(MT) problem, or a Technical Issue(TI) that a reviewer wants to take up with the author(s), or the discussion of the MC has revealed that a more developed solution is necessary, then solution proposals should be postponed to a later date.

In a high-level design, a problem that is MT can significantly affect the productivity of a design review. In such a case, it may be better to halt the review and begin discussion of a solution to this problem.

2.5 Metrics

When the inspection is done, the author will report the number of defects found to the project quality coordinator. The project quality coordinator will keep a running total of all defects found during the different stages in the life cycle of the product. Please note that these numbers will be used solely for quality metric purposes and not for personnel performance evaluation.

3.0 Configuration of the Review

Author Reviewer Facilitator

Pre-Review:

Review:

After Review :

Yes

No

4.0 The Role of the Author

The author’s presence at the review is necessary to answer any question or clear up any ambiguities that reviewers may have. Also, the author is interested in making sure that all defects are found and all design issues are covered. It would be helpful for the all designers to be familiar with The Role of the Reviewer which is also defined in this document. After all, authors are their own personal reviewers.

Input to the design review is either a High-Level Software Design Specification, a Detailed Software Design Specification, or a combination of the two.

4.1 Entrance Criteria

Design review readiness:

• Design has been spell checked.
• Design conforms to architectural specifications.
• Design meets project requirements.
• All known issues have been addressed.
• Above all, the author(s) must feel that the design is ready for review. Whether this means peer reviews, or nothing further is left to the discretion of the author(s).

Review preparation:

• Invite at least two reviewers to attend. Also, give others who may be interested the opportunity to attend by making a general group announcement. However, the number of participants should be limited to about 6.
• Schedule the review at least 1 week in advance to allow the reviewers to have ample time to prepare.
• All reviewers should get a copy of the design.
• Be sure that the amount of material can be inspected in two hours. This can range from 5 to 20 pages but depends on complexity. Large design documents should be split up into manageable pieces for the review session.
• An overview of the material should be presented to facilitate design understanding. Diagrams are often helpful.

If at any point it is discovered that the design contains a defect that would make a review unproductive, or if an inadequate number of reviewers will be present at the review, or if an inadequate number of reviewers have done their preparation for the meeting, then the session should be postponed until such issues are resolved.

4.2 The Meeting

The author will choose one of the reviewers to be the scribe. The scribe will note each issue raised, its severity, and its recommended action. (See 2.4 Defect Ratings and Appendix A: Design Review Worksheet.)

The discussion will begin with an overview of the design and a general question period presented by the author. Then the reviewers take turns going through the design. Design walk through will proceed section by section. After each section of design, there should be a pause to field or express any issues. If a reviewer explains a section that is inconsistent with the author’s intention, then the author should speak up. Perhaps, a note should be made to further clarify that section of the design. The goal here is to make the design universally understandable. That is, a qualified engineer should be able to read the design and understand it enough to be able to code from it.

The design review is an engineering exercise requiring tremendous professional discipline from all involved. The author will not defend the material, for the reviewers will not be attacking it. Any issues raised should be deemed as constructive and honest criticisms. Any comments that are disruptive or hostile should be interrupted promptly. Remember that everyone is working towards a common goal - to produce a high quality product.

At the end of the meeting the scribe will read all the issues aloud.

4.3 Exit Criteria

Meeting is done:

• All new design has been discussed.
• All issues have been raised.
• All actionable issues have been documented.

If an issue exists that is MT, another review should be scheduled once this issue is resolved. If an issue exists that is TI, the author(s) should meet with the reviewer before final approval of the material, but another formal review is not necessary. Issues of rate MC do not need another review. (See 2.4 Defect Ratings.)

It should be noted that though this meeting is done, the designing operation may still persist. The author(s) must follow up on these criteria before the design can proceed into the next phase:

Designing operation done:

• Design meets the most current project requirements and architectural specification.
• Fixes for all defects found by the review have been verified.
• The number of defects found has been reported for metrics to the project quality coordinator.

The next phase is coding.

5.0 The Role of the Reviewer

It would be helpful for the reviewer to be familiar with The Role of the Author which is also defined in this document. This way, reviewers will be aware of the current state of the design and how the meeting will proceed.

5.1 Reviewer’s Checklist

These are the items that the reviewer should be considering while going through the material prior to the meeting:

• Design is correct.
• Design satisfies the most current requirements and architectural specification.
• Material follows guidelines established in project design standards.
• Effective modularity is achieved. Modules are functionally independent.
• Error handling has been specified.
• Comments are sufficient.
• Design is efficient.
• Design can be easily integrated with other project development.
• Design is internationalized and can be easily localized.

Comments and discussion points should be written directly on the reviewer’s copy of the material. Perhaps, a rating of the issue would be helpful. (See section 2.4 Defect Ratings.)

If significant issues or defects are found in the design, contact the author immediately. If the reviewer is not able to prepare in time for the review, contact the author. In either case, the author should consider postponing the review meeting.

5.2 Entrance Criteria

• Design should be read to its entirety with all issues jotted down. This should take no longer than about 2 hours.
• The reviewer should be satisfied that the design is ready for review.

5.3 The Meeting

The author will choose one of the reviewers to be the scribe. The scribe will note each issue raised, its severity, and its recommended action. (See Appendix A: Design Review Worksheet.) The reviewers take turns reading the design aloud. Design walk through will proceed section by section. The reviewers should explain their section as they understand it. If the explanation doesn’t fit with what the author had in mind, then this may be a point that should be noted for further clarification by the author. The point of all this is to make the design understandable by any qualified engineer. At the end of the meeting, the scribe will read aloud all the defects found.

Reviewer’s should resist the temptation to point out corrections in spelling, punctuation, grammar, or expression. These minor corrections should be communicated to the author outside the inspection meeting by submitting a hard copy or electronic copy with these corrections noted. However, if one of these minor problems cause information to be misinterpreted and could affect the final product, those defects should be discussed at the inspection meeting.

All issues previously noted during the pre-review process should be raised at the appropriate times. All comments and defects discussed will be constructive critiques. Expressions of personal criticisms should be interrupted promptly. We must remember that we are all working towards a common goal - to produce a high quality product.

Also keep in mind that the review session should not be a forum for finding solutions to problems. Rather, the session should identify problems or potential problems to which solutions should be discussed at a later date with the appropriate people.

5.4 Exit Criteria

• All new design has been discussed.
• All issues have been raised.
• All actionable issues have been documented.

In addition, reviewers should be available to discuss any important issues personally identified at the review session.

6.0 The Role of the Facilitator

It is often helpful for a third party member, usually quality assurance, to be present at reviews to act as facilitator. The facilitator is one who is familiar with the design review process but need not be familiar with the design.

6.1 Entrance Criteria

The facilitator need only be familiar with the design review process.

6.2 The Meeting

During the meeting, the facilitator will strive to keep the group on track by keeping to the following guidelines:

• Review the product, not the producer. The facilitator should ensure that the review meeting maintains the proper tone and attitude and should immediately halt a review that has gotten out of control.
• Limit debate and rebuttal. The facilitator should make sure that the meeting schedule is maintained.
• Insist upon advanced preparation. A review will be unproductive if the reviewers are not prepared.

6.3 Exit Criteria

The facilitator should make sure that all design issues have been covered and all issues raised have been recorded with the proper people identified to handle any problems.

Conclusion of the design review will state the design is accepted as is, or accepted when corrections are met, or need another design review.

Additional References

Design Review Worksheet

Date 2/1/97

Page 1 of 1

Issues found: Total number of issues found 6

Issues found: Total number of issues found

Design Review Worksheet (continued)

Date

Page ____ of

Design Author(s):

Issues found: