In this article, we’ll take a quick look at 13 code review standards that can dramatically improve the health of your software as well as make your developers happier.
As the name suggests, code review is a process in which one or more developers review code written by another developer (author) to ensure that:
- there are no bugs in the code,
- the code meets all the requirements and standards of quality and style,
- the code does what it is supposed to do,
- when merged, the code won’t damage the codebase.
This is why code review is an important part of software development.
The reviewer acts as a gatekeeper who decides if the code can become part of the codebase and go into production.
Google is known for its technological excellence, and they have effective code review standards that highlight some vital points to keep in mind when conducting code reviews.
The main purpose of code review is to make sure the overall state of the Google codebase improves over time.
Here’s a list of things to keep in mind when reviewing a pull request.
Code review standards
1. The code improves the overall state of the system
Each change (pull request) improves the overall state of the system. The idea is that, as a result of such small improvements, the state of the software or codebase will improve after each merger.
2. Quick code review: responses and feedback
First of all, don’t delay adding (merging) better code. Don’t expect the code to be perfect. If it is in a state that improves the overall health of the system, accept it. The key point here is that there is no such thing as “perfect” code – there is only better code. If you are not in the middle of a specific task, review the code right after it appears. However, one business day is the maximum time it takes to respond to a pull request. Pull requests are expected to receive multiple rounds of partial/full code review in one day.
3. Educate and inspire while reviewing your code
Provide mentorship during code review, foster knowledge sharing whenever possible.
4. Follow standards when reviewing the code
Always remember that style guides, coding standards, and similar documents are the absolute authority when reviewing your code. For example, to ensure consistency between tabs and spaces, you can reference coding conventions.
5. Resolving conflicts during code review
Resolve conflicts by following the agreed best practices outlined in the style guide and coding standards, and by seeking advice and suggestions from others with extensive product knowledge and experience.
If your comments are optional or insignificant, please clarify in your comments and leave it to the author to decide whether to consider them or ignore them. As a code reviewer, you can at least suggest that the pull requests remain consistent with the rest of the codebase in the absence of a style guide or coding standards.
6. Demonstration of UI changes as part of code review
If the pull request changes the user interface (UI), then in addition to the code review, you need to have a demo to ensure that visually everything looks as expected and matches the layouts. For front-end changes, it’s always a good idea to create a demo/walkthrough or make sure the changelog also includes the necessary automated UI tests that validate the added/updated functionality.
7. Make sure code review is accompanied by all tests
Unless it is an emergency, the change request must be accompanied by all necessary tests, i.e. unit, integration, end-to-end, etc. An emergency can be a bug or vulnerability that needs to be fixed as soon as possible, and tests can be added later. In such cases, make sure that the appropriate ticket/issue is created and that someone has taken responsibility for executing them immediately after the fix or deployment.
There is no good enough reason to skip tests. If due to lack of time some goals may not be achieved, then the solution is not to skip tests, but to change the goals to achievable ones.
8. When you’re focused, don’t be distracted by code review
If you are on a specific task, do not get interrupted, as it can take a long time to get back on track. In other words, the cost of breaking away from a focused developer’s work is greater than waiting for another developer to pass code review. Check your code after scheduled breaks, such as after lunch, coffee, etc.
It is not always possible to test all the code in one day. It is important to give the author quick feedback. For example, you won’t be able to do a complete overview, but you can quickly point out a few things to look out for. This will greatly help reduce code review frustration.
9. Go through everything and don’t make any assumptions
Take a look at every line of code you’re asked to look at. Don’t make any assumptions about human-written classes and methods, you must make sure you understand what the code is doing. If you don’t, please clarify this or ask for a step by step guide/code explanation. If there is a piece of code that you are not allowed to review, make sure there are other qualified developers who can review those pieces of code.
10. Review the code with the bigger picture in mind
It is often helpful to look at changes in a broader context. For example, a file was modified and four lines of code were added. Don’t go through just four lines of code–instead, check the entire file and new additions. Do they degrade the quality of the existing code or make the existing function a candidate for refactoring? If simple additions are not considered in the context of a function/method or a class, then over time you will inherit a class that is not supported, very confusing, not testable, does everything, and is difficult to extend or refactor.
Remember that just as small improvements add up over time to produce a great product with fewer defects, so small code degradation or technical debt aggravates over time and results in a product that is difficult to maintain and expand.
11. Recognize and reward good work during code review
If you see something good in the changelog, be sure to thank the author for a good job and encourage him. The goal of code review should be not only to detect bugs but also to reward and praise developers for the great work they do.
12. Be considerate, respectful, kind, and clear when reviewing the code
It is very important that you are kind, clear, polite, and respectful when reviewing your code, and that you are very clear and helpful to the author. When reviewing the code, make sure you write the comment about the code and not about the developer.
13. Explain your comments in code review and be mindful of the volume
Whenever you suggest an alternative approach or hint at something in a code review commentary, it is important to explain why and provide an example based on your knowledge and experience to help the developer understand how your suggestion will help improve the quality of the code. When proposing fixes or changes, find the right balance in how to direct the author to fix the code.
Stay tuned with Software Focus!