Sunny Sharma, David Cross
Performing a Better Code Review is part of a larger 3-part series on Code Reviews. Now that we have gone over the "4 Different types of Code Reviews", we help you perform a better code review. In this blog we address:
- Being a better Reviewer
- Being a better Code Author
- Guidelines on creating Code Review Governance
Being a Better Code Reviewer
To increase your Reviewer’s effectiveness, adopt the following:
- Review no more that 400-500 Lines of Code at a time.
- Review no more than 60 minutes at a time.
- CR should be executed daily, and ideally at the same time of day.
- Use checklists. Ex: Are all requirements met? Is the code unit tested?
Are there security vulnerabilities? - Encourage asking questions about the code to the Author, instead of making statements.
- Provide suggestions with your comments.
- Use Visual aids.
- Accept that there are different solutions to a problem.
- It is acceptable to say that everything looks good and move on.
- Objectively review the code, not the Author.
Use praise for good code. According to April Wensel, a reviewer should always keep this in mind: “Always ask yourself if your feedback is true, necessary and kind.”
Being a Better Code Author
As a code author, it is easy to get emotionally invested in your code. Keep these in mind to be more objective while doing CRs:
- The code is not you. Detach yourself from your code and remember that the Reviewer is offering constructive criticism of the code and not yourself.
- Be humble. Remember that you are both on the same side and want to achieve the same goal of well-written, concise, and error-free code.
- Provide visual evidence of changes with screen prints and sample output. This is particularly the case when you have made UI changes. This can be in the form of before and after screen prints, or output examples. You are saving Reviewer time, and possible aggravation, if they do not have to execute an application to see what the changes are.
- Be the first reviewer: Be your own critic. Before asking others to review, review your code by yourself.
- Provide annotation for important changes.
- Provide a concise title with a Tracking/Reference number.
- Describe the reason (the why) for the code change.
Creating Code Review Governance
After your team has decided on a review type, we recommend you follow these guidelines to make your Code Reviews more effective. Here are the steps we took to creating our Code Review Governance.
Team Code Charter
Develop a Team Code Charter that utilizes quantified methods. For example, your charter might include the following Tenets:
- Demand that code be developed iteratively. This enables early feedback and promotes a continuous testing and integration cycle.
- Manage the requirements and realize that these are dynamic and constantly changing.
Best Practices
Develop and follow proven Best Practices with rules like the following:
- Agreed upon naming conventions for variables, modules, and APIs, etc.
- Indentation rules/style
- Header information - comments
Compartmentalization
Compartmentalization of the code allows your team to find even the smallest details. It also prevents the Reviewer from becoming overwhelmed.
- Break down code into components. This allows tasks to be divided up between team members.
- Visually model the software. There are many tools for this. The goal is to have a roadmap that everyone on the team can use as a reference.
Create a Review Template/Acceptance Criteria Checklist
From your chosen method (based on your organization’s work practises and structure), create a Review Template. This serves as a guideline for newly onboarded members too when they know what is expected of them.
As part of this template, a Code Acceptance Criteria Checklist should be included. For example, in the checklist, you can ask the reviewer questions like such as this:
- Is the same code duplicated in another module?
- Is the code serving more than one purpose? Code modules should have one purpose only.
- Is the code module too big (too many lines of code/handling too many responsibilities)?
Automation
Make your team’s life easier by automating processes where you can. It is always a good idea to automate mundane tasks like:
- Linting. Use a linting program to find issues you might not see by eyeballing the code.
- Create test scripts for unit testing and integration testing.
Quality Testing
Quality should be kept in mind at all times. In the book ‘Understanding and Controlling Software Costs’ the authors state that coding errors (bugs) are one hundred to one thousand times more costly to fix after deployment. The remedy is to be vigilant with security and quality while both coding and reviewing.
In Conclusion
To summarize, code reviews are an integral component in the Software Development Life Cycle. For Authors/Developers, creating code with the expectation that it will be rigorously reviewed, creates better code and developers. Best practise guidelines not only serve to orient new developers, but also assist in creating consistency.
For Reviewers, having a definitive roadmap to follow, allows them to concentrate on the task at hand. They can concentrate solely on Review without feeling ambiguous about what is expected of them.
The improvements resulting from good Code Reviews will be both immediate, and cumulative. Some gains will be realized right away, and some might not be seen for weeks or months.
Ultimately, good code reviews create a better product.