Module 9 Lesson 2: Code review etiquette

Code reviews are one of the most stressful parts of a developer's job. It is the moment where your work is placed under a microscope. If the tone of the review is negative or aggressive, it can destroy team morale.

In this lesson, we learn the "Soft Skills" of code review—how to be a helpful reviewer and a resilient author.

1. Advice for the Reviewer

Use Questions, not Commands

Bad: "Change this to a map."
Better: "Could we use a map here for better performance? What do you think?"

Focus on the Code, not the Person

Bad: "You forgot to handle the error here." (This feels like a personal attack).
Better: "The error handling seems to be missing in this block. Is it handled elsewhere?"

Praise the Good Parts

A code review shouldn't just be a list of mistakes. If you see a clever optimization or a well-named function, say so! Positive reinforcement makes people more receptive to criticism.

2. Advice for the Author

It’s Not About You

When someone critiques your code, they are trying to improve the project, not insult your intelligence. Separate your identity from your code.

Ask for Clarification

If a reviewer leaves a comment like "This is slow," don't get defensive. Ask: "Could you explain why? I'm curious to learn about the performance bottleneck here."

Say "Thank You"

A good review takes time and effort. Acknowledge that effort.

3. The "Nitpick" Rule

Professional developers often use the prefix "nit:" for small, stylistic comments that don't actually affect the code's behavior (e.g., a missing space or a typo in a comment).

This signals to the author: "This is a small detail. I'm okay with you ignoring it or merging even if you don't fix it right now."

graph TD
    Start["New PR Notification"] --> Review["Read Code Carefully"]
    Review --> Logic["Check Logic & Bugs"]
    Review --> Standard["Check Style & Standards"]
    Review --> Tone["Check Your Tone (Is it kind?)"]
    Tone --> Submit["Submit Review"]

Lesson Exercise

Goal: The Tone Edit.

Here is a real (bad) comment from a code review: "This function is confusing and I don't like how you named the variables. Fix it."
Rewrite this comment using the "Empathetic" rules learned in this lesson.
Ensure your new comment is:
- Specific about why it's confusing.
- Phrased as a question or helpful suggestion.
- Professional in tone.

Observation: You'll see that by simply changing a few words, you can turn a conflict-inducing comment into a teaching moment.

Summary

In this lesson, we established:

Empathy is the most important tool in a code review.
Reviewers should use questions and focus on the code, not the author.
Authors should view reviews as an opportunity for growth, not a personal attack.
Use "Nitpick" for non-essential stylistic feedback.

Next Lesson: Back to the technical side. Welcome to Lesson 3: The 'Squash and Merge' vs 'Merge Commit' debate.