Establishing a Code Review Process

In my last post titled “Benefits of Code Reviews”, I described all of the wonderful results that can come from implementing an effective code review process. In this post, I will outline the various approaches to code reviews and provide guidelines for defining a process that will work for your team.

Code reviews can be performed in-person, via emails or by utilizing a tool designed for the purpose. However, before any of these methods are adopted, a well-defined process needs to be established. Without a good process, none of the methods for performing code reviews will produce effective results.

The first step in establishing a code review process is to define the goals that you hope to achieve with code reviews. Goals should be Specific, Measurable, Attainable, Realistic and Timely (SMART). An example of a poorly defined goal for code reviews is “too improve product quality”. Such a goal is far too vague, is not quantified, provides no guidance for determining when it has been met, and has no time-frame target for achieving the goal. A much better goal would be one like the following:

Team X will reduce the number of defects per 100 lines of code changes from the current rate of 20 to less than 10 for Product A within the next three months.

Not only does a goal need to be measurable, but you actually need to perform measurements. In the above example, the measurable quantity is the number of defects per 100 lines of code changes. In order to measure this, you will need to be able to keep track of the number of defects introduced as well as the number of lines of code changes that were made. The means of actually performing such measurements is beyond the scope of this post, but it is something that you need to carefully consider as part of the implementation of the code review process. If you don’t measure the progress toward the stated goals, then you will have no way to know how effective your process is.

The next step in establishing the code review process is to define the workflows.Each workflow will begin with an initiating event, such as a software engineer completing a bug fix or feature enhancement. Each subsequent step in the workflow should either be an action to be taken by an individual, or a decision to be made on which path to take in the workflow. Action steps need to specify what role is to perform the action and what steps are involved in the action. For example, “The submitter will choose another team member as the reviewer and submit the proposed change to them for review”. Decision steps are automatic evaluations of previously set variables to determine which path in the workflow to take from among multiple choices. For example, a decision step could be “if change is less than 5 lines of code, then take peer review path, otherwise take the lead review path”.

There are many suitable flowcharting or process modeling tools that can be used to graphically construct the workflow representation. I highly recommend that you use such tools, as workflow diagrams can greatly aid others with understanding the process. Don’t get too fancy with the workflow though. A complex workflow is less likely to be followed than a simple straightforward one.

The effectiveness of the code review process is heavily dependent on the willing and enthusiastic participation of the reviewers. This can often be a major hurdle when initially rolling out the process for a team, as not everyone may be excited about the prospect of more responsibilities. Such unwilling participants will likely just rubber stamp code reviews without any serious study of the changes. This obviously undermines the entire point of having a code review process in the first place, so such behavior cannot be permitted if the process is to achieve its goals. Following are some suggestions on how to encourage the team members to take code reviews seriously, and to spend the time necessary to do them well:

  • Make the quality of code review responses a factor in determining performance incentives for the team member such as bonuses, raises, etc. This requires a means of monitoring code review responses and assessing the quality of them. For example, review quality could be determined by the number of defects identified per 100 lines of code changes in combination with other similar metrics.
  • Implement a two-level code review process, where first a peer reviews the code changes followed by the team lead or manager reviewing the changes. This way, the peer reviewer knows that it will reflect poorly on them if the lead reviewer catches defects that the peer missed in their review. If the lead reviewer is in a authoritative position over the peer reviewer, this can provide a strong incentive. In cases where the lead reviewer finds defects or other problems that the peer reviewer missed, such problems should be reported to both the peer reviewer and the original submitter so that both can learn from the lead reviewer’s recommendations.
  • Put a cap on the size of code reviews. Spending several hours to review thousands of lines of code changes is not going to be a desirable task for anyone. Limit changes submitted for code review to a few hundred lines at most. Any given code review should not take much more than an hour to complete, and most code reviews should only take a few minutes.
  • Keep code reviews lightweight without sacrificing effectiveness. Use checklists to remind reviewers of common faults to look for, and don’t expect reviewers to find every defect in a given code change. Try to find a good balance between speed and thoroughness of code reviews that works for your team.

Beware of the potential for bottlenecks and delays that code reviews can inject into the software development cycle. For instance, in a process where the team lead performs all code reviews for the other dozen members of the team, the team lead will quickly become a bottleneck. The code review submissions will stack up on his or her plate, especially during times of high development activity, delaying the review feedback for the other team members. In this case, the bottleneck could be minimized by having more than one person handling reviews, or by using peer reviews for simpler changes and lead reviews only for the more complicated changes.

While software developers are used to multi-tasking, and can usually find other things to do while waiting for a code review to be returned, the length of time that it takes to return code reviews inevitably has an impact on the rate of progress. Code reviews should be considered one of the highest priority tasks for reviewers. In most cases, when a reviewer receives a code review, they should set aside whatever other work they were doing, handle the code review quickly but thoroughly, and then return to their original task. Allowing code reviews to sit in a pending state for extended lengths of time will frustrate the submitters and hamper the progress of the project. A rule could even be created that allows the submitter to check-in their changes if the code review is not returned within a specified period of time. The change will still get reviewed later, and if defects or other issues are found, the submitter can then go back and apply the recommended changes.

Expect your code review process to evolve.It is highly unlikely that you will come up with the perfect code review process from the start, or that the same code review process will work effectively for every software development team in your company. Start out with a few basic rules and a simple workflow diagram. As inefficiencies or difficulties with the process are encountered, come up with ways to adapt the process. For example, you might decide that certain classes of trivial changes are exempt from code reviews to help avoid the delay that a code review introduces in cases where a review is truly unnecessary. Make sure that such adjustments to the process are documented and published so that everyone knows what the correct, up-to-date process is.

The time invested in creating and following an effective code review process will pay huge dividends through significant reduction in defects before code changes even reach QA. If you follow my advice about measuring the attainment of the goals set out for the code review process, then you should be able to see the level of improvement in concrete statistics. Even without that, the quality improvements in the software will likely be quite evident.

About Daniel Brannon

Daniel Brannon founded OSoSLO in 2009 to provide software tools and services for business and technology professionals.
This entry was posted in Code Reviews. Bookmark the permalink.

Leave a Reply