Code reviews that work

There are two ways of constructing a software design: one way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. - Tony Hoare

I am a big advocate of code reviews. I strongly encourage every team to adopt code reviews regularly, before merging each one's contribution into the codebase.

Code reviews don't take long and have many benefits:

  • they make developers learn from each other
  • they encourage people to write better code
  • they help disseminating best practices
  • they help keeping the code internally consistent and easier to maintain
  • they reduce costs due to later reworks

In this post I want to summarise some lessons that I have learnt on how to make code reviews that work.

Tips for developers

Keep your code simple. When it comes to good code simplicity is a virtue. Be lean. Do not overcomplicate the solution. Don't try to solve problems that are not yet there. Avoid everything that is not necessary: every line of code that is not needed hides a potential bug.

Keep your code easy to understand. When writing your code think that someone, one day, will have to work on it. Use style conventions that prioritise readability. Use names that are meaningful. Avoid convoluted notations: if there is more then one way to do it, go for the easiest to understand, even if it takes one or two lines more. Comment the most complex parts of your code in a simple, insightful way: don't explain what that line of code does, but rather why it's there.

Accept that you will make mistakes. Remember that the whole point of code reviews is spotting problems, so don't take any criticism personally. Everybody makes mistakes, and reviews are an opportunity to become better developers.

Keep reviews small. Code reviews work well if they don't take long, and if they are frequent and small enough. As a reference try submitting for review no more than 400 lines of code at a time. It's good to have frequent reviews, one every 1-2 days.

Tips for reviewers

Ask questions rather than making statements. Smart people often have strong opinions, and that's fine. Just remember: reviews work better if, instead of just pointing to the problem, they let people see it with their own eyes. Avoid asking «Why did you do X?». Ask instead: «Have you considered Y?».

Use a positive, coaching attitude. Code reviews are opportunities to learn from each other, and sometimes to coach less experienced developers. Be a mentor. Praise for good things, and treat people who know less than you with respect and patience.

Praise for good work. Acknowledging when something is well done is as important as spotting issues, if not even more. Praise developers when they do well and don't make any points when they aren't needed.

Use a checklist. Checklists make reviews simple and more effective. If you are looking for one, my code review checklists are available on GitHub. As always feel free to share your feedback and contributions.