Code Review Guidelines

Code reviews are an important practice for improving the quality of your software and ensuring that it is ready for release. Code reviews are a powerful QA practice and have many advantages over testing:

• A higher percentage of defects are found when using reviews – as high as twice as many than testing.
• When an issue is detected by a review, the root cause of the problem is usually known. Defects found by testing require further work to analyze.
• Reviews can be performed earlier in the development life-cycle than testing.
• Reviews provide more precise and more immediate feedback for developers to learn and improve from than testing.

How to do effective code reviews:

1. Critical and Playful attitude:

1. Critique the code - to find defects, potential problems, or simply poorly-written sections
2. Do not read the code and accept what you see
3. Challenge the assumptions and decisions behind it.
4. Have a questioning, suspicious attitude towards the code you are reviewing.
5. Mentally prepare yourself before starting a review by reminding yourself of the purpose of the review and the need for a critical, questioning attitude.
6. Cultivate a delight or enjoyment in finding issues with the code, like you are playing a game searching for treasures hidden by an opponent.
7. Unearthing a serious defect should feel equivalent to Playing like a Chris Gayle in T20 Cricket.
8. Issues you find will boost your motivation and keep you focused in that critical mindset.
9. Critical attitude required for reviews is similar to the questioning mindset needed for root cause analysis. In root cause analysis, however, we try to determine why something failed, whereas in a code review we try to find all potential causes of failure.

2. Multiple passes through the code :

Use multiple passes to review the code with the initial passes focused on learning about how the code works and later passes focused on critiquing the code.

1. Problem Overview: Review the requirements or specification to understand what the code is supposed to do. What problem is it trying to address? What requirements is it implementing?
2. Solution Overview: Review the design document or specification to learn the overall solution to the problem. How are the requirements being addressed?
3. High Level Organization: Review the code or detailed design document to figure out how the code is organized and functions at a high level. What are the packages and the major classes within each?
4. Major Class Review: Review the code for the most important classes as identified previously. While issues and problems can be found in earlier passes through the code, particularly at the design level, this pass marks the transition from learning about the code to critically analyzing it for problems.
5. Multiple Detailed Review Passes: The previous passes will have given you a sufficient understanding of the code base to critically review the remainder of the code base. Even at this point, however, it is still valuable to use multiple passes. I explain why in the next section.

3. One Goal per class

• Functionality: Does the code meet the business (functional) requirements? Is the logic correct?
• Class Design: Does each class have low coupling and high cohesion? Is the class too large or too complicated?
• Code Style: Is duplication of code avoided? Are any methods too long? Are typical coding idioms / standards followed?
• Naming: Are packages, classes, methods and fields given meaningful and consistent names?
• Error Handling: How are errors dealt with? Does the code check for any error conditions that can occur?
• Security: Does the code require any special permissions to execute outside the norm? Does the code contain any security holes?
• Unit Tests: Are there automated unit tests providing adequate coverage of the code base? Are these junit's tests well-written?

4. Add review comments directly to the code

1. The most effective approach to recording issues is to add them directly to the code base as comments, at the place the issue occurs.
2. Each such comment should be tagged with a special label – use REVIEW – so that the issues can be easily found later by the original developer.
3. In RSA for Java development, define a task tag for this type of comment that will cause all such comments to appear in the Task view.
4. Once the review is completed, the code with the review comments should be checked-in back into the version control system to be made available to the original developers.
5. Produce a review document to comply with processes, create the document at the end of the review from the review comments you added to the code.