INTEGRATED SOLUTIONS

CODE INSPECTION PROCESS

THIS DOCUMENT IS TO BE REGARDED AS THE OFFICIAL CODE INSPECTION 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 Inspection 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

7.0 The Role of the Test Associate

7.1 Entrance Criteria

7.2 The Meeting

7.3 Exit Criteria

Additional References

Appendix A: Code Inspection Worksheet

1.0 Introduction

This document is the Code Inspection Process by which code inspections 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 a revised version of Best Area Practice : Requirements Inspections[1]. It has been revised to fit within the requirements of Integrated Solutions. In particular, emphasis was put on reducing overhead costs while maintaining a quality inspection process. Also consulted for this paper was the Fagan Defect-Free Process[2].

The audience for this document is primarily current and future Integrated Solutions engineers. Code Inspection will be done on all major coding 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 Inspection Process Overview

The code inspection process is a step that occurs before testing. The objective of a code inspection is to find defects!!

The inspection 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 code and listing areas of concern. Each area will be rated.

2.1 Entrance Criteria

• Author(s) has made the code ready for inspection. (See section The Role of the Author.)
• Reviewers and tester(s) have prepared for the inspection. (See section The Role of the Reviewer and The Role of the Tester.)

The author(s) and reviewers must have completed their entrance criteria in order for the inspection 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 will direct the flow through the code. Also one of the reviewers will be designated the scribe, who records all issues and their conclusions. A facilitator will be present to ensure inspection guidelines are kept.

The meeting takes just two hours! If the code 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 inspection is for finding defects and not for providing solutions to defects, which can be very time consuming.

Remember that the inspection 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.

2.3 Exit Criteria

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

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

This inspection process is more or less a verification that code is proceeding in the correct direction. The discovered issues are taken outside the inspection 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 inspection process is complete, the code is ready for testing.

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.

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

3.0 Configuration of the Review

Author Reviewer Tester Facilitator

Pre-Inspection:

Inspection:

After Inspection :

Yes

No

4.0 The Role of the Author

The author is also the inspection guide, as the person who wrote the code knows best the direction discussion should flow. It would also be helpful for the author to be familiar with The Role of the Reviewer, which is also defined in this document. After all, authors are their own personal reviewers.

4.1 Entrance Criteria

Code inspection readiness:

• Programming standards have been followed as defined by project coding guidelines.
• Code compiles "cleanly" as defined by project coding guidelines.
• All known issues have been addressed.
• Above all, the author(s) must feel that the code is ready for inspection. Whether this means some testing, or preliminary peer reviews, or nothing further is left to the discretion of the author(s).

Inspection preparations:

• 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 inspection at least 1 week in advance to allow the reviewers to have ample time to prepare.
• All reviewers should get a copy of the code with line numbers in place.
• Be sure that the amount of material can be inspected in two hours. Usually, this is no more than about 200 lines of code but depends on complexity.
• An overview of the material should be presented to facilitate code understanding. Diagrams are often helpful.

If at any point it is discovered that the code contains a defect that would make an inspection unproductive, or if an inadequate number of reviewers will be present at the inspection, or if an inadequate number of reviewers have done their preparation for the meeting, then the review 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: Code Inspection Worksheet.)

The discussion will begin with an overview of the code and a general question period. Then the author will proceed to go through the code in a manner that is clear to follow and easy to understand. Code walk-through will proceed line by line. After each section of code, the author should pause to field or express any issues.

The inspection process 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.

Keep in mind that the purpose of the inspection is to find defects, not solve them. Solutions to defects will be postponed to a later date for discussion with the appropriate people.

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

4.3 Exit Criteria

Meeting is done:

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

If an issue exists that is MT, another inspection 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 inspection is not necessary. Issues of rate MC do not need another inspection. (See 2.4 Defect Ratings.)

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

Coding operation done:

• Code correctly and completely implements the most current design.
• Code compiles "cleanly" as defined by project coding guidelines.
• Programming standards have been followed as defined by project coding guidelines.
• Fixes for all defects found by inspection have been verified.
• The number of defects found has been reported for metrics to the project quality coordinator.

The next phase is testing.

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 code 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 inspection:

• Code is correct.
• Code satisfies the most current design description.
• Material follows guidelines established in project programming standards.
• Commenting is sufficient.
• Code is efficient.
• Code can be easily integrated with other project development.
• Code 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 code, contact the author immediately. If the reviewer is not able to prepare in time for the inspection, contact the author. In either case, the author should consider postponing the inspection meeting.

5.2 Entrance Criteria

• Code 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 code is ready for inspection.

5.3 The Meeting

The author will guide the flow of the meeting and 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: Code Inspection Worksheet.) At the end of the meeting, the scribe will read aloud all the defects found.

All issues previously noted during the pre-inspection 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 inspection meeting 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.

• All new code 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 inspection meeting.

6.0 The Role of the Facilitator

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

6.1 Entrance Criteria

The facilitator need only be familiar with the code inspection 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 issues raised have been recorded and that the proper people have been identified to handle these 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.

7.0 The Role of the Test Associate

A test associate’s presence at the review session can be beneficial to the code inspection process by presenting an alternate point of view of the material. This can usually be accomplished because a tester’s objectives are somewhat different from a coder’s.

The tester’s preparations and functions at the session are very similar to a reviewer’s.

7.1 Entrance Criteria

The entrance criteria for the test associate are the same as for the reviewers (see section The Role of the Reviewer), with the addition that while the tester is previewing the code, the tester should be pondering the question, "How am I going to test this code?"

7.2 The Meeting

During the meeting, the tester will act as a reviewer. (See section The Role of the Reviewer.) Also, this would be a good time for the tester to ask, "How do you expect me to test this code?"

A good relationship between tester and coder will do much to stimulate development of the product.

7.3 Exit Criteria

The exit criteria for the test associate are the same as for the reviewers (see section The Role of the Reviewer) with the addition that at the end of the meeting, the tester should have a good idea of how to test the code.

Additional References

Code Inspection Worksheet

Date 2/1/97

Page 1 of 1

Issues found: Total number of issues found 6

Date

Page of

Issues found: Total number of issues found

Code Inspection Worksheet (continued)

Date

Page ____ of

Code Author(s):

Issues found: