How to Use Comments and Reviews on GitHub (An Introduction to Code Review)

In the previous article, you took the first step toward contributing to someone else's project using `Fork` and `Pull Request`. However, development isn't complete just by sending a Pull Request. This is where the real fun of team development begins: code review.

Code review is a process where other developers check the code you've written and give you feedback. This allows you to find bugs early, learn better ways of writing code, and improve the overall code quality of the team. In this article, we'll detail how to communicate smoothly on GitHub and how to use the comment and review features for an effective code review.

Code Review Basics: Communicating on a Pull Request

The central place for a code review is the Pull Request page you created. This page consolidates all the information about your changes, and the communication here determines the quality of the project.

GitHub's review features are broadly divided into two types:

• Comment: A feature to casually post questions or opinions on specific lines of code or the entire Pull Request.
• Review: A feature to formally evaluate the entire change and state your intention to "Approve," "Comment only," or "Request changes."

By using these two appropriately, you can facilitate smooth communication.

How to Use the Comment Feature

First, let's look at the easy-to-use comment feature.

1. Commenting on the Entire Pull Request

If you want to ask general questions about the entire change or say thanks, use the comment box at the bottom of the Pull Request page. It's at the very bottom of the "Conversation" tab.

[Image: Screenshot of the comment input field at the bottom of the Pull Request page]

You can post just by entering a message in the text area and pressing the "Comment" button. You can also send a notification to a specific person (mention them) by typing `@username`.

2. Commenting on Specific Lines of Code

The most commonly used feature in code review is this line-by-line commenting. It's perfect for making specific points, like, "Wouldn't it be better if the variable name here were more descriptive?"

1. On the Pull Request page, click the "Files changed" tab.
2. A list of the changed files will appear. Hover your mouse cursor to the left of the line of code you want to comment on.
3. A blue "+" icon will appear; click it.
4. A text box will appear. Enter your comment and press the "Start a review" button.

[Image: Adding a comment to a specific line in the 'Files changed' tab]

At this point, your comment is still in a "Pending" state. It's common practice to gather multiple comments and then submit them all at once as a single review.

3. The Suggestion Feature

If you want to suggest a specific code change, like "It would be better to rewrite it this way," click the "Insert a suggestion" icon (a `+/-` like symbol) above the comment box. A code block will be inserted, allowing you to write your correction directly.

[Image: Using the 'Insert a suggestion' feature in the comment box to propose a code change]

Using this feature is very convenient because the Pull Request creator can apply your suggestion to the code with a single click.

Submitting a Review: Approve or Request Changes

Once you have a collection of comments, you'll finally submit them together as a single "review." Click the "Review changes" button displayed in the upper right corner of the screen.

[Image: Pointing to the 'Review changes' button]

This will display the following three options:

• Comment: Choose this if you're not approving or requesting changes, but simply leaving feedback. Use it for "quick questions" or "personal opinions."
• Approve: This is a declaration of approval, meaning "These changes are great! There are no issues, so it's okay to merge."
• Request changes: This is a request for modification, meaning "These changes require correction. Please fix the points I've indicated before merging."

[Image: Modal window showing the three review submission options (Comment, Approve, Request changes)]

Choose the appropriate option, add a summary comment if necessary, and press the "Submit review" button. Your review will then be formally submitted, and the Pull Request creator will be notified.

Responding to a Review: Correcting and Re-pushing Your Code

Conversely, let's also look at how to respond when you are the creator of a Pull Request and have received a review from someone else.

Step 1: Check the comments and discuss
First, express your thanks for the feedback. If there's anything you don't understand, reply and ask questions. All communication is recorded on the Pull Request.

Step 2: Modify the code based on the feedback
Once you agree with the reviewer's points, modify the code on your local PC. It's even better practice to create a new branch for your work, such as `fix-review-comments`.

Step 3: Push the additional commits
After you've finished making corrections, create a new commit and push it to the Pull Request's source branch (e.g., `fix-typo-in-readme`).

git commit -m "Reflect review comments"

git push origin fix-typo-in-readme

When you push a new commit, the changes are automatically reflected in the Pull Request. There is no need to create a new Pull Request.

Step 4: Resolve finished conversations
Once you've addressed all the points, press the "Resolve conversation" button below each comment to mark the conversation as resolved. This makes it clear at a glance which points have been addressed.

[Image: The 'Resolve conversation' button is pressed and the conversation is collapsed]

Once all conversations are resolved and you receive another "Approve" from the reviewer, it's finally time to merge.