Giving better code reviews – Five principles you should know

4 min read Jul 16 2018
917 0

Code Review is an inevitable process in the Agile work environment as it ensures the quality and consistency of the code, and also encourages knowledge share within the team. Code review is often considered as an excellent tool for mentorship and establishes best practices throughout a development team.

A software developer reviewing the code
A software developer reviewing the code

Everyone involved in the team should decide which factors and rules should be considered for ensuring code quality. During the process, everyone should give their feedback, comments to improve the code quality and correct the bugs using interpersonal skills and individual experience. Most of the programming workflow will include code review at some point in the process, however, all code reviews are not necessarily created the same. It depends on the complexity of the work, familiarity with the code and other factors. Here are some principles we follow to improve the code quality.

Principle #1 : Question everything

When it comes to reviewing the code, don’t make any assumption that the codes will be free of errors and bugs. Just because an experienced developer works on the code, it doesn’t mean there won’t be any bugs. The key is to anticipate mistakes and question every aspect of the code, regardless of the experience and seniority of the developer. Keep the end users in mind, and assume that the developer has made mistakes that you need to correct.

During code reviews always remember this!

Everyone makes mistakes – The developer makes mistakes, so does the code reviewer. If you make a mistake while reviewing the code own it. When everyone in the team is involved in the code review, the chances of identifying and correcting bugs are higher. With someone there to review the code, the developer can focus more on writing the code rather than worrying about the bugs and errors.

Knowledge share – Code review gives everyone in the team an opportunity to learn and grow. The developer gets to learn new ways on how to improve their code while the reviewer understands the advanced techniques from the code they're reviewing. Everyone involved in the process learns something valuable from each other. Everyone learns from a code review!

Principle #2: Review the code thoroughly

During the first phase of the review, obvious mistakes such as typos, poor variable names, unclear function names, small bugs are identified. The first phase is as important as the second phase where reviewers take a lot of time to dig into the code for logical omissions or errors and check all the different aspects that strengthen the code. When you commit to reviewing code, review it thoroughly and keep in mind the following:

Spend a good amount of time: At any stage of code review, don’t just scroll, scroll and accept. Be sure to read the code properly, instead of skimming through it. Apply a great amount of time and thought to the code, its style, and functionality.

Suggest one specific improvement: If you can’t find any mistakes, even after spending a decent amount of time reviewing the code then it suggests that either the code is perfect or that you missed something. When the code is reviewed by someone other than the developer, it gives the benefit of a fresh perspective and therefore you should suggest at least one specific improvement to the code during the early review stages. If at all you find no errors, you should be very sure of that before approving.

Ask questions and research: Code reviewers should be able to understand the code and its objective properly. If there are doubts with any lines of code then do the research and get the required data. Find answers to things you don’t know and come up with better solutions. By gaining more knowledge, you can make better contributions to improving the code quality.

Principle #3: Test the code

It is important to build and test the codes to ensure the code is working properly. Don’t ever assume the code works. Usually, a test plan will be in place for projects, you can use it to try things out. Before testing, make sure you have built the code correctly. If automatic tests are included you should make use of that, as the computer is better at running code than your head is.

You may discover important cases missed while running the code. These findings are highly crucial to ensuring the success of the final product.

Principle #4: Always have comments

Comments are very important when it comes to reviewing. Valuable comments shouldn’t be ignored as the use of comments records important discussion around suggested changes or improvements to the code. Reviewers add comments to the whole review, source file under review, or a line of code. It is also required that the reviewer reply to existing comments by checking recent activity.

Principle #5: Review changes and do the necessary checks

Reviewing can be overwhelming and at times, after considerable time and effort spent on code reviews bugs may evade detection and codes may break. To avoid any major slips, be cautious and double check for errors. Also, follow up on reviews after suggesting changes. Once the new changes are made, don’t assume it is done according to the suggestions but take time to review it again. Make sure all the suggested changes were made, and problems are resolved. Apart from the code, check for the supporting documentation, tests and the build files.

Key takeaways

A code review should be a collaborative discussion and everyone should be able to gain insights and additional knowledge.

Don’t assume the code is free of bugs.

If you are not familiar with the code or concepts, do your research or get extra help from your team. Reviewers are not perfect! Don’t forget to follow up on reviews. Give complete attention to the new changes and review it again.

roud-check left-quote facebook-share-icon twitter-share-icon linkedIn-share-icon forward arrow close-btn Systems Valley on facebook Systems Valley on Twitter Systems Valley on LinkedIn Systems Valley on Youtube Systems Valley on Instagram Systems Valley on Behance