iTranslated by AI
Tips for Enjoying Code Reviews
Introduction
At RubyKaigi 2025, which I attended recently, I purchased a book about code review.
I am currently deepening my understanding by trying out what I learned while reading this book.
In the midst of this, I came across articles with titles like "Code review is scary" and "Characteristics of people who are disliked."
It is true that when you are the one receiving the review, you might feel intimidated by feedback or feel the need to be overly cautious.
However, I feel that code review is by no means something to be "feared," but rather something that can be enjoyed.
Therefore, in this article, I will summarize my own thoughts on tips and approaches for enjoying code reviews.
Points to Keep in Mind for Code Review
By keeping the following points in mind, you will lead to a better review experience, and the review process will become more enjoyable and smoother.
- Are the commit messages appropriate?
- Are the title and description appropriate?
- Final check before submitting for review
- Attitude when receiving a review
Let's look at them one by one.
Are the commit messages appropriate?
When tracing the history of code changes, the first thing you see is the commit message.
If the message clearly shows at a glance what the purpose of the change was and what was changed, it helps in understanding the intent of the code quickly.
Especially when you are not used to it, I recommend breaking commits into small units and attaching a meaningful message for each purpose.
It becomes easier for the reviewer to grasp the changes as a coherent set, which significantly reduces the time and cognitive load required for checking.
I usually create commit messages by referring to the following article:
By carefully separating commits by change content, the PR becomes easier for the reviewer to check, and interactions tend to proceed more smoothly.
Also, when tracing the history yourself later, it becomes clear "where and what you did," which is extremely convenient.
Are the title and description appropriate?
The title is the face of the PR
The title is an important element that determines the first impression of the PR.
You need to concisely and accurately convey the purpose and the implementation.
By making the title allow the purpose and content to be read immediately, you can grasp the overview of the PR at a glance just by looking at the GitHub PR list screen.
Even when the reviewer is busy and cannot devote time to review, they can easily judge "this seems to be easy to check" by looking at the title.
Writing a good title is not only good for the reviewer, but also for yourself.
For example,
Bad example 🙅♂️: "Display flash message on error", "Suppress double submission when button is pressed on admin screen"
Good example 🙆♂️: "Display flash message when user registration fails", "Prevent email sending button from being double-pressed on admin screen"
In the bad example, "what is the fix for?" and "which part is changed?" are unclear, and you won't know the content without opening the PR.
On the other hand, in the good example, the target, purpose, and action are clear, and there is no extra cost to read the content.
By keeping in mind a title that concisely conveys "where," "what," and "why" you did it, the quality and speed of the review will improve, and the flow of the entire development will improve.
Writing a description that is understandable even at a first glance
Even if the content is obvious to the person who implemented it, the reviewer opens the PR without knowing the background or purpose. The major role of a description is to bridge that information gap.
What you should be conscious of here is the perspective of "can the reviewer understand the content even at a first glance?"
In particular, writing with the following information in mind helps the reviewer understand the content smoothly:
- Why this implementation is necessary (background and issues)
- Why this design was chosen (policy and philosophy)
- Results gained through the implementation (expected effects)
- Procedure for operational verification (reference information for the review)
The description is not just an "explanation field," but a place for communication with the reviewer. By having them read the code after properly conveying the premises and background, the review will proceed more smoothly.
Stating the deadline
Another thing I practice is to clearly state the deadline.
I write a deadline in the description, such as "when I want it to be merged by."
When a deadline is clearly stated, it becomes easier for the reviewer to judge the priority of the task. Subtle nuances such as "is this urgent?" or "is it okay to put this off?" are also important clues to prevent miscommunication.
By proactively sharing even small things, you can move the review process forward smoothly.
Example structure of an informative description
## Deadline
This is an urgent PR that I would like to have merged by Month/Day.
## Overview
Fixed a bug where the button displayed on the XX page could not be clicked.
## Background
Since the release last week, there have been reports from users that "the button does not respond."
Investigation revealed that the button was disabled due to a missing style specification.
## How to verify
Start `yarn dev` locally and please confirm that the button can be pressed at http://localhost:3000/XX.
Final check before submitting for review
There are points you should check at a minimum before submitting for review. While they all seem obvious at first glance, they are surprisingly easy to forget in actual development settings.
However, by carefully performing these basic checks, you can minimize the burden on the reviewer, and the review efficiency of the entire team will improve dramatically.
No matter how small the change, by keeping in mind the "state that is easy for the reviewer to check," the quality and speed of the review will change significantly.
By confirming the following points in advance, you can make the review proceed smoothly.
- Does it pass all CI tests?
- Is it narrowed down to one implementation?
- Have you performed operational verification?
Let's look at these one by one.
Does it pass all CI tests?
CI is an abbreviation for Continuous Integration, and it has the following meaning:
CI (Continuous Integration)
A development method that automatically and frequently integrates (merges) code changes into a team's shared repository. When committing code to a repository, you can continuously build and test the code so that errors do not occur due to the commit. Tests can include code linters (checking style formats), security checks, code coverage, functional tests, and other custom checks.
If CI is introduced in your team, it is very important to confirm that CI passes without any issues before submitting a PR.
If you submit a review request while CI is failing, you may need to deal with test or build errors before the review, which can waste the reviewer's time. By following the minimum courtesy of "confirming that CI passes before submitting a PR," you can make the review process go smoothly.
When checking, you can prevent oversights by utilizing the Files changed or Checks tabs displayed in tools like GitHub. Since these tabs display test or build results, errors, and warnings in detail, they are very effective as checkpoints for whether the code is working correctly.
Is it narrowed down to one implementation?
In any project, it is desirable to base your work on the principle of 1 PR = 1 purpose. For example, it is a principle to separate "refactoring" and "bug fixing" into different branches and different PRs. By doing so, "what was implemented in this PR" becomes clear, and you can reduce the cognitive load on the reviewer.
PRs with multiple mixed purposes tend to make it ambiguous to the reviewer "what the purpose of the fix is," which leads to missed points or misunderstandings. Also, even if a bug occurs after the merge, it becomes difficult to identify the cause.
To reduce the cost of rollback, it is important to be conscious of a "PR narrowed down to one purpose."
Have you performed operational verification?
After changing the code, make sure to perform operational verification yourself before submitting the PR. Operational verification is also a minimum courtesy to show that the review is ready.
If you submit it for review without performing operational verification, a pointless rally of "let's fix the bug first" begins, which can also cause you to miss points that should have been pointed out. As a result, the accuracy of the review drops, and the efficiency of the review decreases.
Attitude when receiving a review
Finally, what you need to be conscious of is your attitude when receiving a review. If you keep the following points in mind, code review will become even more enjoyable.
- Do not take comments negatively
- Do not be a yes-man
I will go through these one by one!
Do not take comments negatively
First, you want to understand that "feedback ≠ criticism."
Even if someone's wording feels a bit harsh, it is important not to think that "they might hate me" or "my personality is being criticized." Think of feedback as a chance to grow.
It is natural to be unable to do something at first. You receive feedback during a review and use it for the next time. If the same point is not raised next time, that is proof of your growth.
Also, it is important not to over-read beyond what is written in the text. In text-based interactions, facial expressions and tone of voice are not conveyed, so if you do not understand the intent of a question, you may feel it is aggressive.
Be conscious of accepting comments not negatively, but as positive material. If you do not understand the intent of a comment, you can communicate smoothly by asking something like, "Does this question mean... ?"
Do not be a yes-man
It is also important to have your own intent when responding, rather than accepting everything as it is in response to feedback.
Reviewers are also human. Sometimes the feedback content is wrong. After receiving feedback, it is important to research it yourself and check whether you can be convinced.
If there is a clear reason for the change, try to have a dialogue by saying something like, "I implemented it this way for this reason, what do you think?" Such dialogues and discussions trigger a deepening of the understanding and common knowledge of the whole team.
Do not swallow feedback whole, but cherish the attitude of making changes with your own judgment and responsibility.
Summary
In this article, I summarized tips and approaches to enjoying code review.
- Are the commit messages appropriate?
- Are the title and description appropriate?
- Final check before submitting for review
- Attitude when receiving a review
By keeping the above points in mind, the review will change from a place where you are just pointed out to a place of learning and growth. If you can think that code review is "fun," you will surely love development more. Let's grow one step at a time while stacking up your own ingenuity!
Thank you for reading this far.
I would be happy if you could feel free to comment if you have any questions or impressions! 🙌
References
Discussion