How to Do Code Review: A Team Guide 🔍

Code review is the process of checking another developer’s changes before they land in the main branch. One of the most valuable practices in team development.

Why Code Review Matters

• 🐛 Catches bugs before production, not after
• 📚 Spreads knowledge — reviewer learns from the author and vice versa
• 💬 Documents decisions — discussions in the PR stay forever
• 🎨 Maintains style — code looks consistent regardless of who wrote it
• 🤝 Builds the team — shared responsibility for quality

How to Review: The Reviewer’s Role

Step 1: Read the PR Description

Before looking at the code — read the description. What changed? Why? That’s the context for understanding decisions.

Step 2: Open the Files Changed Tab

Here you’ll see a line-by-line diff:
- 🟢 Green (+) — added lines
- 🔴 Red (-) — removed lines
- ⚪ White — context without changes

Step 3: Leave Comments

Hover over a line number — a blue + button appears.

Three types of comments:

Required change:

There should be a null check here, otherwise we'll crash on an empty description.
Suggestion:
if description is None:
    description = ""

Suggestion (not required):

Suggestion: this could be written more concisely using the walrus operator,
but that's up to you — the current version is fine too.

Question/clarification:

Why is the timeout 30 seconds here and not 10? Is that intentional?

Step 4: Choose Review Type

After adding all your comments, click Review changes:

What to Check During Review

✅ Must check

• Logic: Does the code work correctly? Are all edge cases handled?
• Security: Any SQL injections, XSS, unprotected data?
• Tests: Are there tests for the new functionality?
• PR description: Is it clear what was done and why?

👍 Good to check

• Performance: Any unnecessary database queries, N+1 problems?
• Readability: Are variable and function names clear?
• Duplication: Is someone reinventing something that already exists?

🔎 If possible

• Documentation: Is documentation updated if the API changed?
• Style: Does the code follow project standards?

How to Write Good Comments

❌ Bad

This is wrong.

Rewrite this.

Why did you do this???

✅ Good

There's a potential issue here: if the list is empty, sorted() returns [],
but the next line expects at least one element.
I'd suggest adding a check: if not items: return None

This works, but there's a more idiomatic way using a list comprehension:
result = [item.name for item in items if item.active]
Leaving it as-is is also fine — this is a suggestion, not a requirement.

Rule: A comment should explain what is wrong and why, not just say “bad”.

Review Tone: nit, suggestion, blocker

In professional teams it’s common to label the severity of a comment:

nit: better to name the variable `user_count` instead of `cnt`
(minor, can be ignored)

suggestion: could extract this logic into a separate function
(suggestion, not required)

blocker: there's no network error handling here, this will crash in production
(must fix before merge)

How to Respond to Review: The Author’s Role

Rule 1: Review is about the code, not about you

The comment “this function is too complex” doesn’t mean “you’re a bad developer”. The reviewer is helping to make the product better.

Rule 2: Respond to every comment

Fixed — added a null check, see the new commit.

Good point, agreed. Renamed the variable.

Interesting idea. Leaving it for now because this is temporary code,
but I'll create an Issue to track it.

Rule 3: If you disagree — explain why

I thought about this, but chose the current approach because [reason].
Happy to discuss if you want — open to dialogue.

Rule 4: After making changes — notify the reviewer

After a new push click Re-request review next to the reviewer’s name.
This sends a notification: “author updated the PR, please take another look”.

Common Review Mistakes

Reviewer mistakes

❌ Nitpick bombing — 50 minor comments about spaces and formatting
→ Set up an auto-formatter instead of manual fixes

❌ Silent Approve — clicked Approve without reading
→ If you don’t have time to review — say so, let someone else look

❌ Subjective demands — “I don’t like this style”
→ Review should be about correctness, not taste

Author mistakes

❌ Huge PR — 2000 lines of changes
→ Break into small PRs, they’re easier to review

❌ No description — empty Description field
→ Always fill in the PR description template

❌ Ignoring comments — pushed and merged yourself
→ Respect the review process even when you’re in a hurry

Review in GitHub Desktop

GitHub Desktop doesn’t show the Code Review UI — that’s done through the browser at github.com.

Workflow:
1. Got a PR link → opened in browser
2. Read the description → Files Changed tab → left comments
3. Review changes → chose type → Submit review
4. Author will see the notification in GitHub

Good Review = Good Team

Research shows that teams with a review culture:
- Find 60% more bugs before production
- Onboard new members faster
- Have lower technical debt

Review is an investment, not a waste of time.