Quality Management – Reviews & Walkthroughs

Design reviews and code walkthroughs are two quality assurance activities intended to improve the quality of software produced in the build phase. They are frequently overlooked when planning quality assurance activities, perhaps because they don’t receive the benefits of the marketing campaigns used to sell automated test tools. I highly recommend implementing both these tools as they require no initial investment over and above the time spent on them by the development team. They require no special tools or environments, but must be implemented and run properly in order to yield maximum benefits.

Design reviews and code walkthroughs leverage the collective knowledge of the development team to yield the best designs and code possible. They do this be selecting the optimal number of programmer/analysts, having the optimal technical knowledge, for the review or walkthrough. Careful selection of the reviewers will produce designs and software applications containing minimal errors. These two objectives will reduce re-work costs in the QA and UAT phases of the project.

Design Reviews

The purpose of the design review is to ensure that the design will satisfy the requirements described in the business document it is based on, and will integrate well with the software system being built. This article focuses on the quality assurance process as opposed to the creation of the document, but there are several criteria that any design document should meet before being reviewed. The design document for a software application (or component of an application) describes how the programmer/analyst will create the software that will deliver the requirements described in the business document. It serves the same purpose as a mechanical drawing in the construction industry and must contain the same level of detail.

The design document should contain a description of how the component, or application, fits into the architectural design of the system. This may be accomplished by describing the architecture in the document, or by making the design document integrate with an architectural design document. The document should contain a description of the data elements created or used, the interface design, and the procedural design. The document should not contain code but the writer may use pseudo code to describe complex procedures. It is particularly important that data and architectural design are thoroughly described when the document describes the design of one component of a software system.

The design review is conducted with a team of reviewers under the guidance of a moderator. The moderator ensures that the review stays on point and is the arbiter when disagreements arise. It is the responsibility of the programmer/analyst to gather and distribute the necessary documents and also arrange the time and place for the review. The review is performed in two steps. First the reviewers receive the design document and other related documents such as the business requirements document, architectural document, etc. to analyze on their own. A review date and time is arranged where the observations of the reviewers can be discussed. The observations are in the form of audit points. These points fall in to one of 3 categories: errors, suggestions, and questions. Errors are items which must be fixed before development can begin, suggestions are possible improvements on the existing design and may or may not be implemented, and questions require answers at which point they may become errors or suggestions.

The moderator is chosen by the project manager and should be someone who has sufficient knowledge of the technology and architectural design to spot weaknesses in the design that would not integrate well with the technology or architecture. This person could be the Solution Architect or anyone else with sufficient knowledge including the project manager. They should also be someone who is perceived as a leader by the team members. The moderator is responsible for capturing all the feedback in a review form which is the quality form for tracking the design. The form should capture the comment, the area of the design commented on (by page and paragraph or other reference), the comment’s author, and the type of comment (error, suggestion, or question). The moderator is responsible for deciding whether a comment is an error, suggestion, or question. The moderator ensures the review is completed in the allotted time by making prompt decisions, by keeping the discussion focused, and by cutting off debate. The review form is the deliverable produced by this process and the moderator follows up with the design document author to ensure all errors are corrected and all questions are answered. The author is responsible for indicating which of the suggestions have been incorporated into their design.

The architect and database administrator should be included in the invited reviewers as these roles are critical to the smooth integration of the software component into the system. Anyone responsible for the design of a software component which interfaces with the component under review should also attend. A security specialist may also attend or simply review the document, if your organization has assigned someone to that role. The number of people who attend the review will be determined by the roles your organization has filled and by the size and complexity of the component being reviewed. Choose a team with enough members to apply expertise in all the critical areas of the design but small enough to be agile. A minimum of 4 reviewers are required to provide sufficient input. 6 reviewers will probably be the optimum number to provide maximum expertise and still be agile. Supplement the review team with other team members who will help improve the design with their experience. You may also want to invite junior team members for the purpose of training them in the review process and exposing them to team knowledge in the critical areas of design. The review should compare the design to the business requirements described in the business requirements document to ensure they support those requirements. The design should also be compared to any standards and policies your organization uses.

The moderator should follow the review up and ensure that each of the audit points captured in the review form is closed off before the design is implemented. Setting a timeline for closure is up to the moderator. Errors must be corrected to the moderator’s satisfaction and questions must be answered and the answer communicated to the reviewer who raised the question. The design document’s author should indicate which suggestions have been implemented in their design and the moderator should review these to ensure proper implementation. The programmer/analyst can begin coding once the audit points are closed to the moderator’s satisfaction.

Here’s a tip to avoid those costly disconnects between the user community and the developer: make test cases a part of your design reviews, or have separate reviews for them, and have a business analyst, preferably one who is responsible for the business requirements document, attend the review. Doing this will allow you to catch any misinterpretations before time is wasted on coding and testing code that doesn’t meet the requirements. For an indication of how much time this could save, just identify the bug reports from the last project which identified requirements or functionality as a root cause.

Code Walkthroughs

Code walkthroughs are sometimes referred to as code reviews. This article will use the term code walkthrough here to maintain consistency. The purpose of code walkthroughs is to ensure that code meets all the standards the organization has defined for their code, that the code supports the design described in the design document, and that the code integrates properly with any components it interfaces with. The walkthrough may also suggest a better way to implement a function described in the design, in which case the developer may choose to implement it, or ignore it. The walkthrough is an exercise very similar to the design review. It requires a moderator to facilitate the walkthrough and follow up with review audit points, subject matter experts in data and architecture, and the developers of components that interface with the component being reviewed. Additional developers may be assigned to the walkthrough based on their knowledge and expertise.

The coder is responsible for organizing the walkthrough, selecting the date and time and communicating the code, design document, and any other relevant documents. The code must compile, be unit, function, and thread tested before the walkthrough to avoid wasting reviewer’s time identifying errors that a compiler could identify. The value of the walkthrough is identifying errors and improvements that would otherwise be caught by integration, QA, or UA testing. Code should not be checked into the source library until it has been subjected to a code walkthrough and all audit points closed.

The code and supporting documents should be communicated far enough in advance that reviewers have an opportunity to review the code. The moderator should capture any comments on the code in a form for the purpose. The form should capture the comment, whether the comment is a bug, suggestion, or question, the reviewer who made the comment, and the section of code being commented on. The moderator determines whether a comment is a bug, suggestion, or question and ensures that the code is reviewed in the time allotted. The moderator follows up on the comments captured to ensure that all bugs have been corrected and all questions have been answered. It is up to the programmer/analyst who owns the code to identify suggestions that were incorporated into the code and to communicate the incorporated suggestions to the moderator. The result of the code walkthrough is code that meets organizational standards for code and integrates well with the rest of the software system. The code can now be checked into the source library.

Design reviews should be completed before coding begins and the outcome should be a design that meets all business requirements and integrates well with the system architecture. The design may also provide the programmer/analyst with insight into the best way to solve complex coding problems. Code walkthroughs should complement the automated testing tools chosen for the project. Avoid duplicating effort by ensuring that all bugs identified by the development testing tools have been corrected and any standards enforced by the tools have been complied with. Some standards are subjective in nature and don’t lend themselves to automation. Commenting code is one example of such a standard. A code walkthrough is ideally suited for ensuring that code is sufficiently commented and that the comments clearly describe the functionality of the code.