Code Review – Best Practices, Guidelines & Process Insights

Code review is one of the buzzwords everyone heard about. This technique strictly related to creating software is worth getting familiar with by everyone working in the IT environment. This article is dedicated to technical managers, CTOs, developers, and everyone who work directly with them. I will explain what code review is and why it should be applied to every development team process. Then I will point some pain points and tips and tricks – how to make a code review process more efficient, how to reduce the time overhead and mitigate possible conflicts between the engineers. You will also understand how code review makes codebase better and how to recognize the development team’s problems by carefully watching how code review is performed. What is code review? Before I can explain what code review is, I have to remind you about basic git (code version control system) concepts – branches and pull requests. If you are familiar with code review concept, you can skip to the next section. When developers collaborate on creating new features and fixing bugs, they (hopefully) develop their changes on branches. In git, branches are separate “stages” where code is changed without affecting code on other branches (e.g., other developers features). When a feature is completed, its author creates so-called Pull Request, which is a situation when some changes are requested to be merged to the main branch – so every developer creates features isolated, and in the end, everyone tries to merge them into the main codebase. Finally, code review is the process performed during living pull request, where other developers check the code, comment changes, and perform discussions with the original author about proposed solutions. Code Review Tools – What To Use? Typically there is one platform developers use to keep and maintain their code repository. The most popular code review tools are Github, Gitlab, and BitBucket. You can compare them here. Most of them provide a broad set of features; code review is only one of them. Pro tip: You probably want to keep all code-related data in one place. If you mix tools, try to set integrations. How To Do Code Review? Code review is a discussion. It takes two to tango, so at least one developer has to be involved except the code author, but of course, more developers can – and sometimes even should – join. Typically when code author opens Pull Request, he/she requests reviewers by selecting who should join the discussion – these developers should get notified. Of course, the review can be added without requesting – for example, a developer with free time can help others by adding extra reviews. Code review platform allows developers to see a comparison between the original code and changes proposed by code author. Each line of code can be commented, as well as general comments can be added to Pull Request. Code review can end with three different outcomes: Accepted – when code is fine, and reviewer agrees to merge changes Rejected – where reviewer denies merging and requires changes to the proposed code. Comment – where a reviewer adds remarks but doesn’t make the decision about merging. It can be useful when PR is work-in-progress or developer doesn’t feel competent enough to vouch for checked code. The code review process is a discussion, so sometimes requested changes are applied by the author, but sometimes code author doesn’t agree and discuss the problem with the reviewer. But this cuts both ways – sometimes it is a practical education process which ends with higher code standard, sometimes it’s a long and unproductive discussion (or even a flame!). The goal of code review There are several benefits of performing code review, but each team can focus on a different matter. Typically, the purpose you can look for will be improving general code quality and reducing the number of bugs by sharing knowledge of author and reviewers. Also, developers will educate each other on how to write better code and understand business problems. How much time does the code review process take? Can I afford it? Code reviews can take a lot of time indeed. This process should be added on top of a project’s time estimation. Just like the development itself, it’s tough (for every developer) to estimate how much time it will actually take. Time spent on Code Review will grow with the task complexity, just like the feature implementation. However, you can optimize this overhead, and I will give you some tips later in this article. Keep in mind, that code review is just like agile development – it might feel like we add extra time, but it pays off later with better quality! Why should you require code review in your projects? There are many benefits of having an obligatory code review in your project. Let me show you some of them: Early caught bugs Most likely, the longer a bug exists in your code, the harder it will be detected and terminated. In time, more and more application’s parts can rely on defective code, making it more expensive to fix. A code review will not catch all of them, but an extra pair of careful eyes can see what others don’t. Developers’ experience can vary a lot, one of them could have done a lot of work in previous projects related to, for example, dates manipulation, another one will be experienced in animations or performance. That’s a widespread situation when a developer already solved a problem once and just by looking at the code will know that this or that line will cause trouble in the future. Onboarding new developers Hiring new developers costs a lot – the recruitment process is only a beginning. Before a new developer will become productive and actually “earn” his/her salary, weeks or months will pass. The bigger and more complicated is the project, the longer will be time for a new developer to understand the codebase and business behind it. Code review is a great solution to speed up developers onboarding. A new employee should read the current code, ask questions, and get familiar with how team solves problems and manages the project. Also, when a new engineer starts creating features, quick feedback by the rest of the team will reduce the time required to dive into the project. Two reviewers are better than one It’s not easy to find a consensus if there are two different opinions on the table and two people who have to agree on one of them. Despite how strict computer science can be, there are a ton of problems which solutions based on very non-scientific premises and guesses. Both sides can argue and even fight to prove one’s right. Not many developers have in mind business problems (time!), so they can waste a lot of resources on pointless discussions. Another problem could be the personal character of team members. Sometimes people get frustrated because they can’t push opinion against someone with more communication skills. To solve this problem, it only takes to introduce a third developer (typically second reviewer), who will tip the balance and eventually agree only with one of the parties (or propose another solution). If you have the resources, I recommend having two reviewers by default, but if you lack developers time, add extra reviewer if there is a conflict to solve. Worth to mention that some problems better fit specific issues. Typical developers pair can be more effective when summoning expert from a particular domain to audit the code. So – try to have two reviewers or at least one backup reviewer.