Pull Requests and code review: how to make your code easy to review
I once approved a PR without reading it. Not because I was lazy — because the description was blank, the title was "fix", and the diff had six hundred lines across eleven files with no explanation of what any of it did. I ran out of patience somewhere around file four and clicked Approve. Three days later, it took down the checkout flow in production. That PR had a reviewer. It had an approval.…
A reviewer once approved a pull request (PR) without reading it because the title was simply "fix" and the description was blank. The PR contained 600 lines of code across eleven files, with no explanation of what any of it did. The reviewer's patience ran out around the fourth file, and they clicked "Approve" anyway. Three days later, the PR caused the checkout flow to crash in production. The PR concept itself is useful, but its effectiveness depends on how it's written.
The anatomy of a PR that gets reviewed quickly includes a clear title, a well-written description, and a concise set of instructions for testing. The title should indicate what the PR does in the imperative mood, such as "feat(auth): add JWT token refresh mechanism" or "fix(cart): prevent duplicate items when clicking fast." The description should answer three questions: why the change is being made, a summary of the main changes, and instructions on how to test the changes. If the change is visual, screenshots should be included.
PR size also affects review quality. A 200-line diff can be carefully read, while an 800-line diff forces reviewers to look for an "Approve" button to get out of the process. Large features should be broken down into smaller PRs, each focusing on one thing. The rule of thumb is to create one PR per thing. Large features can be broken down by component, business logic, or integration.
To create a PR from the terminal, use the GitHub CLI (gh). Authenticate once with gh auth login, and then create a PR using the gh pr create command, specifying the title, description, and reviewers. The web interface is useful for PRs with screenshots or when your team has a description template configured. Requesting review explicitly by assigning reviewers in GitHub or using the gh pr edit command ensures that the right people see the PR and can provide feedback.
Draft PRs are useful for early feedback on the direction or approach before the code is fully developed.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
