Being Reviewed, and Reviewing Others

Code review is where beginners learn fastest and feel worst, often in the same afternoon. It is worth naming that plainly before the mechanics, because the discomfort is universal and it is not a sign that anything is wrong.

Both halves are skills. Reading someone's change usefully is one. Receiving comments on your own without taking them personally is the other, and it is the one that takes practice.

What a reviewer does

They read the change, ask questions, suggest improvements, and then either approve it or ask for changes.

On GitHub the comments attach to specific lines of the diff, so the conversation happens where the code is rather than in a separate thread. A reviewer can also leave a general comment on the pull request as a whole, which is where "this looks good, one question" belongs.

Responding

Two legitimate responses to any comment, and one bad one.

You can make the change: commit it and push to the same branch, and the pull request updates itself.

git add index.html
git commit -m "Use the club's official wording for the meeting day"
git push

Or you can reply explaining why you did it that way. That is a normal, useful contribution to the conversation, and reviewers are wrong reasonably often.

The bad response is silence. A pull request that has been sitting for three days with an unanswered question is not waiting on the reviewer; it is waiting on you.

Reviewing well

When you are the one reading, a few habits make the difference between a review that helps and one that irritates.

Say what you would change and why. "This is confusing" gives the author nothing to act on; "this reads as though the meeting is weekly — could it say 'first Thursday'?" gives them a sentence.

Separate "this is wrong" from "I would have done it differently". Both are worth saying, and they are not the same thing, and the author cannot tell which you mean unless you say so.

Approve when it is good enough, not when it is perfect. A reviewer hunting for something to object to is wasting the mechanism, and everyone can tell.

Say what you liked, once. Not as decoration — because it tells the author which instincts to keep.

Taking review well

The comments are about the change, not about you. That sentence is easy to say and takes about six months to feel, and it helps to know that in advance.

The uncomfortable comment is usually the one worth acting on. "Good catch, fixed" is a complete and professional reply. And "requested changes" is not a rejection: it is the ordinary state of most pull requests, including those written by people with fifteen years of experience.

Openthe proposal

→

Reviewcomments on lines

→

Commit and pushsame branch

→

Approvemay take a few rounds

Suggestions

GitHub lets a reviewer propose an exact edit to a line, which the author can accept with one click. It turns a paragraph of explanation into a two-second fix, and it is the politest way to say "I think this word is wrong".

Accepted suggestions become commits on the branch with the reviewer recorded as a co-author, while whoever clicked to apply them is the committer. It is a small and pleasant piece of honesty about who wrote what.

On Sandpiper

Theo reads your meeting-time pull request and asks why the time appears twice on the page. You look, and it does — the header and the footer both say it, which means the next change will have to remember both.

You push one more commit that puts it in a single place, and reply saying so. The pull request now contains the fix, the reason, and the improvement that came out of the conversation. That is what review is for, and no part of it was about you.