A Guide to Code Inspections Jack G. Ganssle [email protected] The Ganssle Group PO Box 38346 Baltimore, MD 21231 (410) 496-3647 fax (410) 675-2245A Guide to Code Inspections © 2001 The Ganssle Group. This work may be used by individuals and companies, but all publication rights reserved. There is a silver bullet that can drastically improve the rate you develop code while also reducing delivered bugs. Though this bit of magic can reduce debugging time by an easy factor of 10 or more, despite the fact that it’s a technique well known since 1976, and even though neither tools nor expensive new resources are needed, few embedded folks use it. Formal code inspections are probably the most important tool you can use to get your code out faster with fewer bugs. The inspection plays on the well-known fact that “two heads are better than one”. The goal is to identify and remove bugs before testing the code. Effectiveness Those that are aware of the method often reject it because of the assumed “hassle factor”. Usually few developers are aware of the benefits that have been so carefully quantified over time. Let’s look at some of the data. The very best of inspection practices yield stunning results. For example, IBM manages to remove 82% of all defects before testing even starts! One study showed that, as a rule of thumb, each defect identified during inspection saves around 9 hours of time downstream. AT&T found inspections led to 14% increase in productivity and tenfold increase in quality. HP found 80% of the errors detected during inspections were unlikely to be caught by testing. HP, Shell Research, Bell Northern, and AT&T all found inspections 20 to 30 times more efficient at testing in detecting errors. IBM found inspections gave a 23% increase in productivity and a 38% reduction in bugs detected after unit test. So, though the inspection may cost you 20% extra time during coding, debug times can shrink by an order of magnitude or more. The reduced number of bugs in the final product means you’ll spend less time in the mind-numbing weariness of maintenance as well.A Guide to Code Inspections © 2001 The Ganssle Group. This work may be used by individuals and companies, but all publication rights reserved. The Inspection Team The best inspections come about from properly organized teams. Keep management off the team! Experience indicates that when a manager is involved usually only the most superficial bugs are caught, since no one wishes to show the author to be the cause of major program defects. Four formal roles exist: the Moderator, Reader, Recorder, and Author. The Moderator, who must be very competent technically, leads the inspection process. He or she paces the meeting, coaches other team members, deals with scheduling a meeting place and disseminating materials before the meeting, and follows up on rework (if any). The Reader takes the team through the code by paraphrasing its operation. Never let the Author take this role, since he may read what he meant instead of what he implemented. A Recorder notes each error on a standard form. This frees the other team members to focus on thinking deeply about the code. The Author’s role is to understand the errors found and to illuminate unclear areas. As code inspections are never confrontational, the Author should never be in a position of defending the code. An additional role is that of Trainee. No one seems to have a clear idea how to create embedded developers. One technique is to include new folks (only one or two per team) into the code inspection. The Trainee(s) then get a deep look inside of the company’s code, and an understanding of how the code operates. It’s tempting to reduce the team size by sharing roles. Bear in mind that Bull HN found four person inspection teams are twice as efficient and twice as effective as three person teams. A code inspection with three people (perhaps using the Author as the Recorder) surely beats none at all, but do try to fill each role separately. The Process Code inspections are a process consisting of several steps; all are required for optimal results. The steps are: Planning - When the code compiles cleanly (no errors or warning messages), and after it passes through Lint (if used) the Author submits listings to the Moderator, who forms an inspection team. The moderator distributes listings to each team member, as well as other related documents such as design requirements and documentation. The bulk of the PlanningA Guide to Code Inspections © 2001 The Ganssle Group. This work may be used by individuals and companies, but all publication rights reserved. process is done by the Moderator, who can use email to coordinate with team members. An effective Moderator respects the time constraints of his colleagues and avoids interrupting them. Overview - This optional step is a meeting for cases where the inspection team members are not familiar with the development project. The Author provides enough background to team members to facilitate their understanding of the code. Preparation - Inspectors individually examine the code and related materials. They use a checklist to ensure they check all potential problem areas. Each inspector marks up his or her copy of the code listing with suspected problem areas. Inspection Meeting - The entire team meets to review the code. The Moderator runs the meeting tightly. The only subject for discussion is the code under review; any other subject is simply not appropriate and not allowed. The person designated as Reader presents the code by paraphrasing the meaning of small sections of code in a context higher than that of the code itself. In other words, the Reader is translating short code snippets from computer-lingo to English to ensure the code’s implementation has the correct meaning. The Reader continuously decides how many lines of code to paraphrase, picking a number that allows reasonable extraction of meaning. Typically he’s paraphrasing 2-3 lines at a time. He paraphrases every decision point, every branch, case, etc. One study concluded that only 50% of the code gets executed during typical tests, so be sure the inspection looks at everything. Use a checklist to be sure you’re looking at all important items. See the “Code Inspection Checklist” for details. Record all errors and classify them as Major or Minor. A Major bug is one that if not removed could