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