One of the most important tasks for a developer is code review. In a tech team, sometimes it takes a while to get code review approvals for many reasons. Developers have different points of view when checking each other's code.
Why is it important to follow best code review practices and how it affects the health of our codebase?
A day with doctor McKayla 👩🏻💻
Not long ago we had the chance to meet Dr. Michaela Greiler, the code review expert. It was awesome to get feedback from someone who accelerated engineering teams at Microsoft. Together, we had a workshop about fast and effective code reviews where we discussed how to improve our current process.
Unreviewed code is two times more likely to show defects.
When we do code reviews, we focus on many things. Some developers might focus on code readability, others on the coding style and so on. But what are the pain points of this process?
- Low feedback quality
- Large code reviews
- Waiting too long for approvals
- Performance pressure
- Time pressure
At Microsoft, developers spend a significant amount of their time on code reviews.
After identifying some of the pain points, we focused on how to improve our code reviews.
Two sides of the coin
It is important to think about reviewing code when you're writing code. Keep in mind that others will read and evaluate it. Think about how much time you have to spend on providing explanation and guidance.
Focus on making things clear and as self-explanatory as possible. When in doubt, try answering questions like "Will others understand this piece of code?" or "Does this class name explain what the class really does?".
Not a huge chunk of code at once. It is more complicated to review a lot of files and lines of code that affect different dependencies. Therefore; a lot of bugs might escape without being noticed.
A good solution would be to decide within the team how many changes are acceptable within a pull request.
At Google, 90% of all code changes comprise less than 10 files and 24 lines of code. On average, code reviews are completed within 4 hours.
Another thing to tackle are single commits. Best practices for git commits like cherry-picking and good commit messages help a lot in organizing the changes and making them more readable. Here are some of the best practices for git commits to use:
- Small commits
- Good commit messages
- Code editor for longer commit messages (-m "<message>")
- Practice with command line
Giving proper feedback 🎯
Asking questions is a very good approach. It leads to a nice dialog between the coder and the reviewer. This way, you learn from each other's perspective and decide together on the solution.
Rather than giving commands, focus on giving suggestions in a nice way. If you don't like that variable's name, try suggesting another one by asking the coder's opinion.
Explain yourself when you are commenting on a piece of code. When you think something is hard for you to read or there is a simpler way to do it, write a good comment by giving guidance and describing the reason.
For ex. "What do you think of naming this variable to user_phone_number instead of user_mobile_phone_number? It is shorter and it doesn't change the meaning."
Make your point to the code, not the coder. Another important thing is to always refer to the code. Pointing fingers is a bad habit. Instead of saying "You didn't close the socket connection here!", try "The code isn't closing the socket connection".
Last but not least, make it a bug finder challenge!
As coders, our time is precious. We focus on delivering fast and effective code. Quality and speed are important in providing software. Writing and reviewing code is challenging and we tend to follow the best practices. Code reviews are important tasks in our day-to-day work. Attending workshops, reading and practicing the best approaches help us deliver great software.