Readability counts even in code reviews
There are many guides all around the web on giving a good code review. Most of them will tell you what to look for (possible security issues, design, performance, etc.), what guidelines to follow (maximum time spent on a code review or a number of lines read at a time, creating checklists, etc.), or which tools can help you speed up your code reviews (like automated coding standard checks in pipelines).
Today, I would like to take a more holistic look at code reviewing and talk about a few things to keep in mind when you want to deliver a clear and understandable code review.
When looking for general tips on what a good code in Python is and how to get closer to writing it, Python luckily comes bundled with the Zen of Python. If you are not familiar with it, it is a set of 19 useful principles on writing code. [1] Out of all of these, a few stand out to me regarding code reviews — especially Readability counts, which is closely tied to Code is read much more often than it is written. [2] From the latter, you can probably already see the connection. But how should you apply such a general principle when doing code reviews?
When reading someone else’s changes
One way of applying Readability counts is this — try to picture yourself as the person that is, two years from now, trying to find and fix a bug in the code you are now reviewing.
Why? You are in the best position to see the obstacles and unclarities people could face in the future. However, you have a small advantage in your case — the production environment isn’t (hopefully) burning down.
When reading the code, try to focus on what they could struggle with.
Is there a part of the code that is entangled and difficult to understand, a naming that could be misleading, or maybe a missing comment explaining unexpected (and at first sight) odd behaviour?
Fixing seemingly minor readability issues like this now can save a lot of people a lot of time and head-scratching. Spending five more minutes on the changes can save an hour for someone in the future. And likely multiple times.
When writing code review comments
The same approach of Readability counts can be applied on comments once you have all your code review notes together. Code reviews are a great place to share knowledge and different ideas. So, if the comments are understandable, both the author’s and the code reviewer’s coding skills can benefit from it.
A good way to achieve that is to phrase comments as suggestions, and then follow them with reasoning as to why such a solution could be beneficial. The author likely had their own reasons for using a different approach than the one you thought of. There probably isn’t just one correct solution to the problem. If you incite them to share those reasons, you can then learn from their point of view — the same way they can learn from your comments. Also, no one likes to do something just because someone else said so.
All this doesn’t mean that you should throw every useful trick and tool for better code reviews into a trash can. When reviewing someone else’s changes, it’s good to keep in mind the people that will read the code in the future as well as the author reading your code review comments.
What’s your approach to delivering a clear and understandable code review? Let me know in the comments or join us to share some ideas in person.
