12  Collaborative Software Development

This chapter covers the social side of writing code together: reviewing each other’s work and responding to review feedback.

12.1 Code Review

When submitting code to or reviewing code from colleagues, use best practices to provide and receive constructive feedback:

12.1.1 Responding to review comments

Once you receive a review from a human reviewer, you are obligated to respond promptly: typically within a week, unless there are extenuating circumstances. Address each of the reviewer’s comments individually. You aren’t obligated to agree with every comment; you are entitled to ask clarifying questions, raise objections, or ask to defer it to a later pull request.

When a reviewer leaves a comment on your code, respond to each one with exactly one of these:

  • Address it. Make the change the reviewer asked for.
  • Rebut it. If you think the code is correct as written, explain your reasoning and push back. You can disagree—just say why.
  • Defer it. If the comment is valid but out of scope for this change, file a tracking issue, assign it to yourself (or delegate it, if applicable), and link it in your reply so the reviewer can see you are taking their concern seriously. This keeps the work visible and ensures it is not lost.
  • Acknowledge it. For a comment that needs no action, a short acknowledgment is enough.

Never ignore a review comment. Always reply—even if only to say you filed a follow-up issue.

12.1.2 Avoid closing and restarting pull requests

Avoid closing a pull request and “starting over” on the same issue. Doing so disrupts the conversation between authors and reviewers, creates confusion, and leads to repeated work. Instead, keep iterating on the open pull request, where the review history stays attached to the code it discusses.