PR Etiquette: my pet likes, hates

2025-02-22 · tech

It's time to talk about Pull Requests. I enjoy PRs — they can tell a story. A well-formulated PR leaves the reader knowing what you did, why you did it, and how.

Try not to look at them as a necessary evil, but as a fantastic opportunity for learning and collaboration.

Why Pull Requests Matter

PRs are your way of saying: "Hey team, I want to propose some changes." They help:

  • Share knowledge — everyone gets to see and learn from each other's code
  • Collaborate — a PR is a proposal; use it to discuss and improve code together
  • Maintain quality — catch bugs and ensure consistency; four eyes are better than two

My Tips for Creating a Great Pull Request

Keep it short and sweet

Smaller PRs are easier and faster to review. Aim for around 200 lines of code or less — it maintains review quality and efficiency.

Break down big tasks into smaller chunks. Instead of one massive PR for a new feature, split it into PRs for the backend logic, frontend interface, and tests.

Be clear and descriptive

A good description helps reviewers understand your changes quickly. Use a template like:

**What:**
Briefly explain what you've changed.

**Why:**
Explain why this change is needed.

**How:**
Describe how you've implemented the change.

Always test before you push

Run your project's test suite and any new tests you've added. Mention the testing you've done in your PR description.

See PRs as learning opportunities

PRs are a two-way street. Both authors and reviewers can learn from each other. Be open to criticism. Ask questions. Share your thought process.

Tips for Reviewing a Pull Request

Be kind and constructive

Positive feedback encourages growth and maintains a friendly team atmosphere. Highlight what's good, suggest improvements, and explain your reasoning.

Review promptly

Timely reviews keep the project moving and show respect for your teammate's efforts. Don't LGTM just to get the review out quickly — read it and give honest feedback.

Set aside regular times to review PRs, and communicate if you're delayed.

Focus on the big picture

It's easy to get lost in minor details and miss larger issues. Ensure the code aligns with project goals and doesn't introduce new problems.

Common Pitfalls to Avoid

Submitting huge PRs (my pet hate #1)

Large PRs are tough to review and delay feedback. Keep them small and focused. If a PR is getting too big, split it.

Being vague in descriptions

Reviewers won't understand the purpose or context of your changes. Provide clear, detailed descriptions and link to any relevant issues or discussions.

Taking feedback personally

Code reviews are about the code, not you. Embrace feedback as a chance to learn and improve.

Final Thoughts

Pull requests are more than a code review tool — they're a platform for collaboration and learning. By keeping them concise, clear, and constructive, you not only improve the codebase but also grow as a developer.

Happy reviewing.

Further reading: GitHub — Helping others review your changes · Atlassian — The written and unwritten guide to pull requests