Code Reviews, Inline Comments, Approvals and Changes Requested

Code reviews are the primary defense against software bugs, architectural rot, and security vulnerabilities. On GitHub, the Pull Request interface provides a comprehensive suite of review tools designed to foster collaborative learning and high engineering standards.

1. The Anatomy of a GitHub Code Review

When a teammate asks you to review their Pull Request:

1. 1
   Navigate to the PR on GitHub and click the Files changed tab.
2. 2
   Review the diffs line by line. Additions are green (+), deletions are red (-).
3. 3
   Hover your mouse over any line of code and click the blue + icon to start an inline comment.

+-----------------------------------------------------------------------------+
| Line 42: const userToken = jwt.sign(payload, "secret_key_123");             |
+-----------------------------------------------------------------------------+
| [Review Comment]                                                            |
| Hey! Let's avoid hardcoding secrets in source files. Can we use             |
| `process.env.JWT_SECRET` instead?                                           |
|                                                                             |
| [ Add single comment ]           [ Start a review ]                         |
+-----------------------------------------------------------------------------+

Single Comment vs. Starting a Review:

• Add single comment: Posts immediately and notifies the author right away. (Can be noisy if you leave 10 comments).
• Start a review (Recommended): Batches all your comments into a "Pending" draft. You can refine them and publish all comments at once when your review is complete.

2. Suggesting Code Changes Directly

Reviewers can do more than point out problems—they can provide ready-to-commit solutions! Click the Add a suggestion icon (+-) inside the comment box:

const userToken = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '1h' });

The author can click Commit suggestion directly in GitHub, instantly incorporating your suggested code without switching back to their terminal!

3. Submitting the Review: The 3 Verdicts

Once you have examined the files, click Review changes in the upper right. Choose one of three verdicts:

4. How the Author Addresses Review Feedback

If a reviewer requests changes:

1. 1
   Do not open a new PR!
2. 2
   Simply make the requested edits locally on your machine on that same feature branch.
3. 3
   Commit the fixes and push:

1. 1
   GitHub automatically appends the new commits to the existing Pull Request and updates the diff!
2. 2
   In GitHub, click the Re-request review circular arrow icon next to the reviewer's name.