Gandalf: White Wizard, Code Reviewer

Too many cooks spoil the broth.

Rare is the system with only one developer to support it. Managers will happily add bums to seats in a project to meet deadlines, fill a skill gap, or any other reason they can think of. The more the merrier you might say, and I won’t dispute that, but growing a team is not without consequences.

The problem is we are all unique individuals with different backgrounds, preferences and skill sets. Meaning, two developers might give two different solutions for the same problem. For just one problem this won’t matter, but as developers come and go over the years your code base will turn into a patchwork quilt of different coding styles, repeated code, and various re-inventions of the wheel.

Sounds familiar? Keep reading.

Code review, or peer review

A code review is simply the process where any written code is examined by the author’s colleagues before the code is allowed to be pushed into the repository. It’s a chance for the whole team to learn from mistakes, not point the finger of blame.

Pros and cons

Done right the only downside to code reviews is an upfront investment of time. Meaning, you spend time fixing problems before they actually turn into problems. The technical debt will grow at a reduced rate as a result. Yes, code reviewing will take time. Especially so for the more senior members of staff, but code reviewing is a skill and they will become faster and better given time.

There is a social benefit to it as well. When you know one, or more, of your colleagues will look at your code you also make sure you do your very best.

The pros are numerous:

  • consistency every problem has many solutions, and code reviewing is your best chance of making sure the there is only one wheel in your application.
  • readability by enforcing style guidelines and by refactoring overly complicated code your code base will be easier to understand and maintain in the long run.
  • training code reviewing is a great way to bring new developers up to speed on your code base, your coding standards, and industry best practices your organisation uses.

What about bugs?

This might come as a surprise, but the purpose of a code review is not to find bugs. Sure, bugs will be found, but most of them will be trivial. You do code reviews for the long term benefits, like maintainability, and it’s the job of your testing suite to prove the code works.

What do you need before you start?

  • tools Gerrit, Github, Crucible and Barkeep are all examples of code review suites.
  • style guidelines examples of how to write clean, readable code. Style guidelines are more about formatting than technical issues.
  • coding guidelines examples of how to write code adhering to your paradigm and language of choice. Joshua Bloch’s Effective Java is pretty much the industry standard for Java developers across the world.
  • dependencies list list of third party libraries which are allowed in the code base.
  • module specifics specifics for modules, for a web layer this could be related to security.

Process overview

  1. coder writes code with tests.
  2. coder submit for review.
  3. coder continues to work in another branch.
  4. reviewer reviews and submits feedback.
  5. coder updates his code, or asks reviewer to explain his/her comments if needed.
  6. goto 2 or submit if code is approved.

You will also need a list of approvers, those who can actually sign off a piece of code so it can be submitted. This could simply be your senior developers, or those with particular domain or technology expertise. It’s a good idea to test a person before you give them permission to approve code, to make sure they really know the ins and outs of your guides.

Code of conduct

You are not Gandalf.

Basically, don’t be a dick. Be constructive in your criticism and use examples to get your point across. Pay attention how you phrase your comments. It’s better to be humble and respectful than try and force your opinion on others. You are not Gandalf, and the other developers are not Balrogs, and must be allowed to pass. Eventually.

Speed is also important. Try and do the review as quickly as possible, and if you feel you do not have time reassign it to someone else.

Make sure to use examples to get your point across. It’s your chance to teach your colleagues to adhere to company guidelines and industry best practices.