Last updated on 27th of January.

Please also read Code Review Guidelines Part 2.

What is a Code Review?

Code review is systematic examination (often known as peer review) of computer source code. It is intended to find and fix mistakes overlooked in the initial development phase, improving both the overall quality of software and the developers’ skills.

Why Reviews are important?

Quoting from Code Complete: A Practical Handbook of Software Construction, Second Edition

.. software testing alone has limited effectiveness — the average defect detection rate is only 25 percent for unit testing, 35 percent for function testing, and 45 percent for integration testing. In contrast, the average effectiveness of design and code inspections are 55 and 60 percent. Case studies of review results have been impressive:<!--more-->

• In a software-maintenance organization, 55 percent of one-line maintenance changes were in error before code reviews were introduced. After reviews were introduced, only 2 percent of the changes were in error. When all changes were considered, 95 percent were correct the first time after reviews were introduced. Before reviews were introduced, under 20 percent were correct the first time.
• In a group of 11 programs developed by the same group of people, the first 5 were developed without reviews. The remaining 6 were developed with reviews. After all the programs were released to production, the first 5 had an average of 4.5 errors per 100 lines of code. The 6 that had been inspected had an average of only 0.82 errors per 100. Reviews cut the errors by over 80 percent.
• The Aetna Insurance Company found 82 percent of the errors in a program by using inspections and was able to decrease its development resources by 20 percent.
• IBM’s 500,000 line Orbit project used 11 levels of inspections. It was delivered early and had only about 1 percent of the errors that would normally be expected.
• A study of an organization at AT&T with more than 200 people reported a 14 percent increase in productivity and a 90 percent decrease in defects after the organization introduced reviews.
• Jet Propulsion Laboratories estimates that it saves about $25,000 per inspection by finding and fixing defects at an early stage.

The main goals of code review are:

1. To spot and fix defects early in the process.
2. Better-shared understanding of the code base as team members learn from each other
3. Helps to maintain a level of consistency in design and implementation.
4. Helps to identify common defects across the team thus reducing rework.
5. Builds confidence of stakeholders about technical quality of the execution.
6. Uniformity in understanding will help interchangeability of team members in case of non-availability of any one of them.
7. A different perspective. “Another set of eyes” adds objectivity. Similar to the reason for separating your coding and testing teams, peer reviews provide the distance needed to recognize problems.
8. Pride/reward. Recognition of coding prowess is a significant reward for many programmers.
9. Team cohesiveness. Working together helps draw team members closer. It also provides a brief respite from the isolation that coding often brings.

Let’s see how important is to fix potential defects from the development phase:

The main areas a reviewer is focusing on are as follows:

• General Unit Testing
• Comment and Coding Conventions
• Error Handling
• Resource Leaks
• Thread Safety
• Control Structures
• Performance
• Functionality
• Security
• Compliance with existing Design & Architecture
• Proper use of 3rd party libraries

Roles and Responsibilities

1. Developer: is the person who has written the code to be reviewed and has initiated the review request.
2. Reviewer/s: are the people who are going to review the code and report the findings to the developer.

Tips for the Developer:

1. The primary reviewer is the author i.e. YOU.
2. Create a checklist for yourself of the things that the code reviews tend to focus on. Some of this checklist should be easy to put together. It should follow the outline of the coding standards document. Because it’s your checklist, you can focus on the thing that you struggle with and skip the things that you rarely, if ever, have a problem with. Run through your code with the checklist and fix whatever you find. Not only will you reduce the number of things that the team finds, you’ll reduce the time to complete the code review meeting—and everyone will be happy to spend less time in the review.
3. You are not your code. Remember that the entire point of a review is to find problems, and problems will be found. Don’t take it personally when one is uncovered.
4. Understand and accept that you will make mistakes. The point is to find them early, before they make it into production. Fortunately, except for the few of us developing rocket guidance software at JPL, mistakes are rarely fatal in our industry, so we can, and should, learn, laugh, and move on.
5. No matter how much “karate” you know, someone else will always know more. Such an individual can teach you some new moves if you ask. Seek and accept input from others, especially when you think it’s not needed.
6. Don’t rewrite code without consultation. There’s a fine line between “fixing code” and “rewriting code.” Know the difference, and pursue stylistic changes within the framework of a code review, not as a lone enforcer.
7. The only constant in the world is change. Be open to it and accept it with a smile. Look at each change to your requirements, platform, or tool as a new challenge, not as some serious inconvenience to be fought.
8. Fight for what you believe, but gracefully accept defeat. Understand that sometimes your ideas will be overruled. Even if you do turn out to be right, don’t take revenge or say, “I told you so” more than a few times at most, and don’t make your dearly departed idea a martyr or rallying cry.
9. Don’t be “the guy in the room.” Don’t be the guy coding in the dark office emerging only to buy cola. The guy in the room is out of touch, out of sight, and out of control and has no place in an open, collaborative environment.
10. Please note that Review meetings are NOT problem solving meetings.
11. Help to maintain the coding standards. Offer to add to the coding standards for things discussed that aren’t in the coding standards. One of the challenges that a developer has in an organization with combative code review practices is that they frequently don’t know where the next problem will come from. If you document each issue into the coding standards, you can check for it with your checklist the next time you come up for code reviews. It also will help cement the concept into your mind so that you’re less likely to miss opportunities to use the feedback.

 Tips for the Reviewer

1. Critique code instead of people – be kind to the coder, not to the code. As much as possible, make all of your comments positive and oriented to improving the code. Relate comments to local standards, program specs, increased performance, etc.
2. Treat people who know less than you with respect, deference, and patience. Nontechnical people who deal with developers on a regular basis almost universally hold the opinion that we are prima donnas at best and crybabies at worst. Don’t reinforce this stereotype with anger and impatience.
3. The only true authority stems from knowledge, not from position. Knowledge engenders authority, and authority engenders respect – so if you want respect in an egoless environment, cultivate knowledge.
4. Please note that Review meetings are NOT problem solving meetings.
5. Ask questions rather than make statements. A statement is accusatory. “You didn’t follow the standard here” is an attack—whether intentional or not. The question, “What was the reasoning behind the approached you used?” is seeking more information. Obviously, that question can’t be said with a sarcastic or condescending tone; but, done correctly, it can often open the developer up to stating their thinking and then asking if there was a better way.
6. Avoid the “Why” questions. Although extremely difficult at times, avoiding the”Why” questions can substantially improve the mood. Just as a statement is accusatory—so is a why question. Most “Why” questions can be reworded to a question that doesn’t include the word “Why” and the results can be dramatic. For example, “Why didn’t you follow the standards here…” versus “What was the reasoning behind the deviation from the standards here…”
7. Remember to praise. The purposes of code reviews are not focused at telling developers how they can improve, and not necessarily that they did a good job. Human nature is such that we want and need to be acknowledged for our successes, not just shown our faults. Because development is necessarily a creative work that developers pour their soul into, it often can be close to their hearts. This makes the need for praise even more critical.
8. Make sure you have good coding standards to reference. Code reviews find their foundation in the coding standards of the organization. Coding standards are supposed to be the shared agreement that the developers have with one another to produce quality, maintainable code. If you’re discussing an item that isn’t in your coding standards, you have some work to do to get the item in the coding standards. You should regularly ask yourself whether the item being discussed is in your coding standards.
9. Remember that there is often more than one way to approach a solution. Although the developer might have coded something differently from how you would have, it isn’t necessarily wrong. The goal is quality, maintainable code. If it meets those goals and follows the coding standards, that’s all you can ask for.
10. You shouldn’t rush through a code review – but also, you need to do it promptly. Your coworkers are waiting for you.
11. Review fewer than 200-400 lines of code at a time.

Security Code Review

If the applications requires a very close attention to security then www.owasp.org is the right place for resources. This is a very good Security Code Review document to consider: https://www.owasp.org/images/2/2e/OWASP_Code_Review_Guide-V1_1.pdf

Assign Severity to Review Findings

The severity to find issues with code should go as below. Reviewer must focus on issues with High severity first and then to Medium severity and then Low severity issues.

1. Naming Conventions and Coding style = Low
2. Control Structures and Logical issues = Medium or High
3. Redundant Code = High
4. Performance Issues =High
5. Security Issues = High
6. Scalability Issues= High
7. Functional Issues =High
8. Error Handling = High
9. Reusability = Medium
10. Design & Architecture = High
11. Proper use of 3rd party libraries = Medium

Checklist for developers and reviewers

Checklists are a highly recommended way to find the things you forget to do, and are useful for both authors and reviewers. Omissions are the hardest defects to find – after all, it’s hard to review something that’s not there. A checklist is the single best way to combat the problem, as it reminds the reviewer or author to take the time to look for something that might be missing. A checklist will remind authors and reviewers to confirm that all errors are handled, that function arguments are tested for invalid values, and that unit tests have been created.
Another useful concept is the personal checklist. Each person typically makes the same 15-20 mistakes. If you notice what your typical errors are, you can develop your own personal checklist (PSP, SEI, and CMMI recommend this practice too). Reviewers will do the work of determining your common mistakes. All you have to do is keep a short checklist of the common flaws in your work, particularly the things you forget to do. As soon as you start recording your defects in a checklist, you will start making fewer of them. The rules will be fresh in your mind and your error rate will drop. We’ve seen this happen over and over.

Checklist for Developers

 Checklist for Reviewers

I also made them in checklist format to be printed: CodeReview_ChecklistforDevelopers, CodeReview_ChecklistforReviewers.

Continue reading Code Review Guidelines Part 2.

Recommendations

References:

1. http://www.codinghorror.com/blog/2006/05/the-ten-commandments-of-egoless-programming.html
2. http://www.developer.com/java/other/article.php/3579756
3. http://www.smartbear.com/docs/BestPracticesForPeerCodeReview.pdf
4. Peer Reviews in Software: A Practical Guide
5. http://www.techrepublic.com/article/developers-guide-to-peer-reviews/1050834
6. http://smartbear.com/SmartBear/media/pdfs/best-kept-secrets-of-peer-code-review.pdf