Forth-eV Wiki

by Kim Harris and Michael Ham

Programmers frequently need to understand in detail a program that was written by someone else. Understanding other people's programs is essential in program maintenance and revision, and it also plays a valuable role in programmer education by allowing programmers to learn from the techniques and skills embodied in their colleagues' creation, as well as from their mestakes and oversights.

Formal CODE INSPECTIONS efficiently facilitate the difficult task of truly comprehending a program. This technique has the added advantage that the use of and inspection TEAM menas several people learn the program at one time. The team approach also ensures that the program is inspected from various viewpoints; thus, inefficiencies and errors are more likely to be detected.

Code inspetion provides an execllent way for members of a FIG chapter to work together through the examples of FORTH code bublished in FORTH Dimensions and other journals. This technique helps the chapter members learn from the code and from each other.

A code inspection team consists of four to six members; more or fewer hinder the process. Larger FIG chapters can form several inspection teams. In a company environment, it is important that supervisory or managment personnel not be on the team, since their pressence has a chilling effect on the frankness of the criticism and on the open give and take of the process

Special roles are assigned in advance to individual team members.

One team member takes the role of the author of the code. Ideally, of course, the actual author will play this role, but in the absence of the true author, a stand-in will suffice. The purpose of the author is to be the expert who answers question about the code: why a given approach was taken, what considerations led to the development of a particular word. The author's ultimate responsibility is to make the appropriate changes to the code.

The moderator's role is to keep things moving and to keep the inspection session on track. The idea of the code inspection is to understand the code and to point out ways in which it falls short: errors, inefficiencies and the like. This meeting, though, is not the place to write new code or to develop alternate solutions. The moderator is a facilitator who keeps the meeting focused on its purpose. Also, every suggestion and correction must be recorded during the meeting so that it will not be forgotten. The moderator is responsible for the minutes of the meeting.

One team member reads the code aloud, paraphrasing it in terms of its purpose, rather than merely echoing the actual definitions. Instead of: Next is SUM-COUNTS. ONE RECORD-COUNT STORE BEGIN FETCH-RECORD….

the reader says something like:

The next word begins with the first record; for each record, it reads the total and increments the count box.

By paraphrasing the code, the reader focuses the group's attention on the meaning of the code: by paraphrasing it aloud, the group stays together and actually examines each word. Without such a reading, code inspections quickly degenerate into:

Next is screen 10; any comments? No? Screen 11? Screen 12?

The process goes faster, but the code is not really examined or understood.

The remaining team members are inspectors. They follow the code as the reader reads it, ask questions ofthe author, and point out what they question or don't understand. Some inspectors may be asked to pay special attention to program functions in their area of expertise (eg. drivers, data-base desigh, quality assurance, integration, testing).

All members of the team check the code for style: Are the names well chosen? Are stack diagram present and accurate? Are comments present and helpful?

To prepare for a code inspection, each person should spend two hours carefully reviewing the code to become familiar with it and to get some grasp of how it does what it does. The reader, of course, may have to prepare in greater detail, since to paraphrase the code requires a good understanding of its intentions.

Preparation is vitally important to the success of the code inspection.

The meeting should be limited to two hours; people cannot focus with any intensity for a longer period of time. Experience shows that a line of FORTH code requires (on average) about thirty seconds in this kind of review; this means a screen can be covered in about seven minutes. The result is that a review of FORTH code cannot normally cover more than about seventeen screens in any session; twenty is probably the maximum.

After the code inspection, the author revises the code to take into account the comments and criticisms offered by the inspection team. COmpared to uninspected code, the code resulting from this process of review and revision shows a number of improvements: the style and factoring are better and more understandable, which makes subsequent maintenance and revision much easier. Reviewing the code with other programmers catches problems that would normally show up only later, when the various separate module would be integrated–problems like the use of the same name for different functions, redundancy with other modules ( as when a programmer redevelops a routine that another programmers has already written and tested), inconsistency in data values, and mismatches of context or side effects. Experince has shown that formal code inspections increase productivity, reduce development time and cost, and contribute to programmer training and education.

The literature on code walk throughs and team programming is extensive. A good starting place for the interested reader is:

The Psychology of Computer Programming by Gerald Weinberg.