← Library

— notes

Review Your Own PR First

2 min read#engineering-practices
On this page
  1. What Happens Without Self-Review
  2. Why Self-Review Matters
  3. a. Saves Time
  4. b. Improves Code Quality
  5. c. Builds Trust
  6. How to Self-Review
  7. a. View the Diff As Someone Else
  8. b. Check Commit Messages
  9. c. Document Special Considerations
  10. d. Validate Tests
  11. e. Check Style and Linting
  12. What Happens With Self-Review
  13. Self-Review Checklist

Like most developers, I’ve been on both sides of Pull Requests. What I’ve noticed is that the best PRs, the ones that get merged smoothly with minimal back-and-forth, are where the author has already done a thorough self-review.

What Happens Without Self-Review

sequenceDiagram
    participant Author
    participant Reviewer
    Author->>Reviewer: Push PR for review
    Reviewer->>Author: 12 comments (typos, dead code, naming)
    Author->>Author: Fix trivial issues
    Author->>Reviewer: Push fixes
    Reviewer->>Author: 5 more comments
    Author->>Author: Fix again
    Author->>Reviewer: Push fixes
    Note over Author,Reviewer: 3+ round trips before merge

Why Self-Review Matters

a. Saves Time

Clean up obvious issues yourself so reviewers focus on architecture and design.

b. Improves Code Quality

Reading your own diff catches patterns that don’t jump out when you’re writing.

c. Builds Trust

A polished PR signals respect for your colleagues’ time.

How to Self-Review

a. View the Diff As Someone Else

Open the Files changed tab and read every line as the reviewer.

b. Check Commit Messages

Follow conventional-commit style. Each commit should represent one logical change.

c. Document Special Considerations

Add inline comments for non-obvious decisions.

d. Validate Tests

Run them locally. Check coverage for success and failure paths.

e. Check Style and Linting

Run your formatter and linter before requesting review.

What Happens With Self-Review

sequenceDiagram
    participant Author
    participant Self as Self-Review
    participant Reviewer
    Author->>Self: Read own diff as reviewer
    Self->>Author: Catch 12 trivial issues locally
    Author->>Author: Fix naming, dead code, edge cases
    Author->>Reviewer: Push clean PR
    Reviewer->>Author: 1 substantive design comment
    Author->>Author: Address feedback
    Author->>Reviewer: Push final fix
    Note over Author,Reviewer: 1 round trip to merge

Self-Review Checklist

graph TD
    Start["Open your PR diff"] --> A{"Diff readable?\nClear naming?"}
    A -->|Yes| B{"Commit messages\nclear and atomic?"}
    A -->|No| A1["Fix naming"] --> A
    B -->|Yes| C{"Tests pass?\nCoverage adequate?"}
    B -->|No| B1["Rewrite commits"] --> B
    C -->|Yes| D{"Docs updated?\nPR description clear?"}
    C -->|No| C1["Add tests"] --> C
    D -->|Yes| E{"Linting clean?"}
    D -->|No| D1["Update docs"] --> D
    E -->|Yes| F["Ready for review"]
    E -->|No| E1["Run linter"] --> E

The simplest habit that pays the biggest dividends: before clicking “Request Review”, open the Files changed tab and read every line as if a colleague wrote it.