Today I listened a great podcast episode Episode 400: Michaela Greiler on Code Reviews, where Michaela Greiler talks about how to do great code reviews. I have to say, that I love this topic and the tips Michaela gives are so great, that I want to share some of them with you.
Code review is all about code quality
First thought of code reviews is usually, that they are helping us to find bugs, but actually that is a common misunderstanding. Microsoft Research has find out that 15% of changes related to code review are bugs and 50% are about quality (Microsoft, Code Reviews do not find bugs). So most of the code review comments are not about bugs, they are about the quality of the code.
Code reviews are expensive
Code reviews does not come without a cost. It takes developers time to read the code, write comments and maybe even test it on their own machine. If three or four of the reviewers does all these things, then it is clearly expensive. Because code reviews are expensive, they should always add value. Value can be learning, getting better code or even finding some bugs, but as learned from previous chapter, this is poor method to find bugs. Before creating the code review think first, does it add any value? Do I want others to learn from this code, do I need others to comment my architectural decisions or am I a bit unsure about my solution and need some other opinion to proof it? Don’t create code reviews because you have to.
How to write great code review comments
As a code reviewer, your job is to add value to reviewed code in a positive and constructive manner. Being positive and constructive can be hard sometimes, but there are some good rules to follow:
- Ask questions over being dictate. Leave final decision to code review creator and give suggestions. “Could this variable be renamed as CustomerOrder?” vs. “This variable should be CustomerOrder”.
- Phrase comments as I messages. “I don’t understand this part of the code, could it be written more clearly?” vs. “This code is hard to understand.”. It is more emphatic when reviewers give some of their own feelings into comments.
- Write comments about code under review. Don’t comment code that is already in repository. Use other method to tackle those problems. People don’t want to hear comments about old code.
- Give feedback as soon as possible. Few weeks old comments does not help much.
It is also good have a checklist of things that are under code reviews. Finding bugs, security, naming, commenting etc. It is important to agree on the rules of code reviews before starting to do them. So everyone knows what is expected of them.
Use different methods
Pull requests aren’t the only way to do code reviews. Peer review on one machine is powerful and maybe also the fastest way to execute code reviews. Pull requests are good when you want to achieve asynchronous review process. Submit the PR and continue working with other task.
As Michaela notes in the podcast, one way to execute the review is to do the PR first and then start developing the feature (or fixing bug). This way the reviewers can monitor the whole implementation process, not just ready product.
All methods have their advantages and disadvantages. Pick suitable method based on your needs.
You can listen the whole episode from SE Radio website: