Agile is all about constant improvements. We do retrospectives, we improve our delivery pipelines, we make our work more transparent, and we also do code quality improvements.

The most famous code quality improvement practice is code review. Code review is basically a process of verifying and improving your code quality. It not only helps you make your code better but also helps to educate your teammates. Code reviews can differ in many ways. You can use different tools to share changes and comments or you can just do a face-to-face review and fix everything in real-time.

The pitfalls of code reviews

Bad code reviews can harm your team and lower software quality if you don’t apply them properly. How come? Code review is a communication tool. People are fragile, and people make mistakes. Connect the dots.

If you are too sloppy, you will end up with messy code. If you’re too rigid, you will break the team unity and create a stalemate. So, how can you overcome these problems? Here are some tips.

1. Order your code review goals
2. Be precise and descriptive
3. Be motivating and give a good example
4. Automate as much as possible

1. Order your code review goals

Code review will not fix all code flaws. You need to focus on the most important things.  What is the most valuable outcome of a code review? There is no obvious answer. For instance, a team may value discovering vulnerabilities over improving code readability. If you order these goals, you can focus on important stuff. I suggest writing down all the code review goals, and order and share them across the team. A list of goals may also highlight bad practices the team should abandon or things that should be covered by using another tool other than code review.

Here is the example of an ordered code review goals list:

• Discover architecture issues
• Discover performance issues
• Inspect changed APIs
• Improve code readability
• Teach good practices
• Find naming mistakes
• Discover bugs
• Discover vulnerabilities
• Find typos
• Find code style issues
• Laugh over sb else’s code
• Spend some time on sth else other than programming

You can agree on goals in many different ways. One of them is to create a stylesheet. For instance:

2. Be precise and descriptive

You find a code issue or you may write a two-word comment to fix it. You may also describe:

• What is wrong with the code
• How does it impact the solution
• How to fix the problem

Which approach is better? The rule of thumb is to answer these three questions. It improves developer experience tremendously. Developer experience is very important, especially if you work in a distributed team.

You could ask how many lines of code you can review on a single day. The intention is obvious: to stay focused. But we are not creating simple procedures these days. Our code is split into functions, classes, modules, and sub-applications. You can set a lines-per-day limit. However, it might prevent you from seeing the bigger picture. I suggest checking your code review goals and decide if a lines-per-day limit makes sense to you. If you run into a code review size problem try to focus on a single goal, starting from the top of the list.

3. Be motivational and give a good example

As I said before, a code review is a communication process. You communicate possible code flaws. Your teammate communicates if he agrees with you or not. Sounds simple, right? Unfortunately, it can get really messy when emotions get in the way. There are a couple of problems.

First of all, software developers are often tied to their solutions. You know this image, right?

If you try to force your approach, you might end up arguing about spaces vs tabs.  You know you’re right. Your colleague knows he’s right. You’re both wrong. What is the outcome of such an argument? Wasted time and higher tension for sure.

The second thing is that developers try to work like compilers by finding all the mistakes and waiting until your teammate fixes them. It tends to punish minor flaws while ignoring major improvements. How is your teammate suppose to know that he should repeat the very same approach the next time?

The last issue is also connected with the compiler-like code review. If the pull request creator won’t fix all the comments, then you won’t approve the PR. The code review comments should make the product better. The product gets better when the team gets better. If you push your teammates too hard they will start treating your requests as too rigid and ignore them. There is no point commenting on issues then.

The productive way of doing code reviews allows step-by-step improvements. You want to experience better CRs? Start changing your behaviour first. If you follow the rules below, you will share the positive and professional attitude across your team. The rules are simple:

• Stop treating code personal.
• Compliment good solutions.
• Gradually improve your coworkers’ skills & knowledge.

4. Automate as much as possible

A code review requires huge amounts of attention. Fortunately, there are lots of tools that can make your life easier. Many code flaws have been discovered by code analyzers. Some of them point out code style issues, whils others discover possible vulnerabilities or performance issues. Some of them find spelling mistakes and words that are not allowed in your public API code docs.

We can recommend a couple of tools if you work on .NET/JavaScript stack:

• StyleCop.Analyzers – a tool for C# applications that searches for code style issues
• ESLint – a tool for JavaScript code that makes JS syntax more strict (e.g. by enforcing semicolons at the end of statements)
• SonarQube – a continuous integration tool that searches for common code flaws (duplication, vulnerabilities etc.)
• custom .NET Analyzer– you can write your own .NET code analyzer that works similar to StyleCop.Analyzers but is focused on your custom needs

Remember that automation is more valuable if it works on all developers’ machines as well as on the CI server.

Conclusion

There are plenty of ways to improve your code review. However, the most important thing is to be aware of your team and product needs and craft the code review implementation adequately. Always keep in mind that code review is a communication process – the better you explain it, the more value it gives. In order to reduce the scope of conversation, automate validation of repeatable stuff that the team have already agreed on.