Best Practices for Pull Requests

Growing as an engineer: Write small pull requests At my first job, we didn’t do code reviews at the beginning, and later one when the company started to do review, my code was still not reviewed because I was the only person working on frontend/node.js code. When I started at Google, the first pull request I sent (or changelist as it’s called at Google) was about 3000 lines of code. It took a few days to get approved and maybe just 2-3 passes, but looking back – it wasn’t the best way to proceed. I just didn’t know as I never reviewed code before and never had to have my code review. Sending code to be reviewed is similar to having a discussion about your project. You have to structure your presentation – first give context/problem, then describe at a high level the solution and finally go deep into each section one by one. The way to achieve this with code changes are: - Write a clear description of your code change (the context, what your change is doing, what are the follow PRs coming up, what are the risks etc.) - Break down your changes into chunks that a person can easily process – someone can easily understand a high level skeleton, or a detailed but short-ish implementation. It’s very hard for someone to parse a multi-thousands line code change. The interesting thing is that you will likely be able to merge your code faster by sending X small PRs rather than one massive one even if you’ll need more interactions with the reviewers – your reviewer will just take significantly more time to review your massive PR. The drawbacks of large PRs don’t stop here though: - The review you’ll get for a massive PR will less thorough as people will dread doing it and may skim over some parts - You will waste more time if changes are needed – e.g. if your approach wasn’t good, you have to discard more work than if you had sent just a skeleton - Getting your code in production might take more time because your changes will likely trigger more pre-merge tests (since more code is being changed) and in case a rollback is needed, you will have to roll forward more code (and maybe deal with more merge conflicts) Sending human reviewable changes is a useful skill to have – it’s one of the little things that you never have a chance to learn about at school. Bonus: Interesting illustration based on the prompt "cartoon of a software engineer breaking a change in small pieces"

I've reviewed 1,000+ pull requests. This paradox is real. The uncomfortable truth: We're terrible at reviewing large changes. Our brains literally give up. What happens with big PRs: – Reviewers skim instead of reading carefully – Focus shifts to obvious syntax issues and missed architectural problems – "LGTM" becomes the default response to avoid spending 2+ hours – Critical business logic bugs slip through unnoticed – Technical debt compounds because no one catches design flaws The psychology: Large diffs create "review fatigue." After 400+ lines, your brain switches to pattern matching instead of critical thinking. Real solution most teams ignore: – Break features into 100-200 line chunks – Review business logic separately from UI or API changes – Use draft PRs for early architectural feedback – Set team limit: No PR over 300 lines without exceptional justification The cost: That 500-line "looks fine" PR? It probably contains 3-5 bugs that will surface in production and 2-3 design decisions you'll regret in 6 months.

Git Pull Request Workflow 0. 𝐒𝐭𝐚𝐫𝐭 𝐰𝐢𝐭𝐡 𝐚 𝐂𝐥𝐞𝐚𝐧 𝐒𝐥𝐚𝐭𝐞 ➟ Before beginning any work, ensure your local repository is synced with the latest code from the remote main branch. git checkout main git pull origin main ➟ Create a descriptive branch for your feature or fix git checkout -b feature/add-user-authentication ➟ Use a clear, consistent naming convention for branches (e.g., feature/, bugfix/). 1. 𝐌𝐚𝐤𝐞 𝐋𝐨𝐠𝐢𝐜𝐚𝐥, 𝐀𝐭𝐨𝐦𝐢𝐜 𝐂𝐨𝐦𝐦𝐢𝐭𝐬 ➟ Develop your feature or fix in small, logical chunks. ➟ Each commit should address a single, meaningful unit of work. git add src/auth/ git commit -m "Ticket 1234: implement JWT token generation" 2. 𝐏𝐮𝐬𝐡 𝐘𝐨𝐮𝐫 𝐁𝐫𝐚𝐧𝐜𝐡 𝐭𝐨 𝐑𝐞𝐦𝐨𝐭𝐞 ➟ Once you’ve completed your local changes, push your branch to the remote repository. git push -u origin feature/add-user-authentication ➟ Create a pull request (PR) through your Git platform (e.g., GitHub, GitLab, Bitbucket). Include: - A clear title summarizing the change. - A detailed description explaining the purpose, implementation, and potential impacts. - Links to related tickets, issues, or documentation. - Screenshots or videos for UI/UX changes. 3. 𝐂𝐨𝐝𝐞 𝐑𝐞𝐯𝐢𝐞𝐰 𝐏𝐫𝐨𝐜𝐞𝐬𝐬 ➟ Automated Checks - CI/CD pipeline should run tests, linting, and static analysis to validate the code. ➟ AI augmented Feedback - Tools like CodeRabbit can provide immediate, context-aware suggestions for: - Code style inconsistencies. - Common bugs or anti-patterns. - Security vulnerabilities. - Performance optimizations. ➟ Human Review - Teammates should evaluate: - Architecture and design. - Maintainability and scalability. - Alignment with business logic and requirements. - Adherence to coding standards. Tip: ➬ Encourage open, constructive discussions during reviews. ➬ PRs are an opportunity to collaborate and improve, not a battleground. 4. 𝐊𝐞𝐞𝐩 𝐘𝐨𝐮𝐫 𝐁𝐫𝐚𝐧𝐜𝐡 𝐔𝐩 𝐭𝐨 𝐃𝐚𝐭𝐞 ➟ Keep your feature branch synced with the target branch (e.g., main) to avoid conflicts later. 5. 𝐅𝐢𝐧𝐚𝐥 𝐏𝐫𝐞-𝐌𝐞𝐫𝐠𝐞 ���𝐡𝐞𝐜𝐤𝐥𝐢𝐬𝐭 ➟ Before merging your PR, ensure the following - ✅ All CI checks pass (tests, linting, builds). ✅ Required approvals are obtained from reviewers. ✅ All review comments are addressed with follow-up commits. ✅ Documentation is updated (e.g., README, API docs). ✅ The branch is up to date with the target branch (perform a final rebase if necessary). 6. 𝐌𝐞𝐫𝐠𝐞 𝐭𝐡𝐞 𝐏𝐑 ➟ Choose the appropriate merge strategy based on your team’s workflow - - Squash Merge [Combines all commits into one for a clean history.] - Rebase Merge [Maintains a linear history while preserving individual commits.] - Merge Commit [Creates a merge node, preserving the full commit history.] ------- Remember, A good PR isn’t about showing how much you’ve done, it’s about making it easier for someone else to understand and build on your work. 🤗 #git

I've reviewed 1000+ pull requests. Here's what separates great engineers from the rest. It's not cleverness. It's clarity. 1/ Write the "why" in your PR description. What problem does this solve? Spending two minutes here saves your team 20 minutes of confusion. 2/ One change per PR. When you bundle refactoring with new features, reviewers can't tell what matters. Split them. 3/ Comment on decisions, not code. Don't explain what getUserById() does. Explain why you chose this approach over alternatives. 4/ Test the edge cases. What happens when the API is down? When the list is empty? Great engineers think through failure modes. Clever code gets you noticed. Clear code gets merged, deployed, and trusted. This kind of thinking is what I help engineers develop into a tech lead. Weekly insights in my newsletter. Link is 👆

💡 𝟳 𝗧𝗶𝗽𝘀 𝗳𝗼𝗿 𝗖𝗿𝗲𝗮𝘁𝗶𝗻𝗴 𝗘𝗳𝗳𝗲𝗰𝘁𝗶𝘃𝗲 𝗣𝘂𝗹𝗹 𝗥𝗲𝗾𝘂𝗲𝘀𝘁𝘀 ✅ Well-crafted PRs keep projects moving forward smoothly. Follow these tips to create PRs that actually get reviewed and approved quickly: - ➕ Make small, targeted changes instead of huge 1000+ line PRs that are hard to review - 📝 Add a descriptive title and clear description explaining the changes so reviewers understand the context - 🔗 Link to any related issues or supporting documentation to provide background - 🖼️ Include screenshots and gifs to demonstrate the changes rather than just describe them - 👥 Tag reviewers and request feedback from teammates to get eyes on the PR faster - ✅ Include a test plan to verify your changes and give confidence they won't break things - 🚀 Describe the deployment strategy and rollout plan so reviewers understand the impact - 🤔 Add context on why the changes are needed and their impact to justify the effort What tips do you have for creating effective pull requests? Share in the comments - let's help each other improve! #dev #programming #softwaredevelopment #pullrequests

if (!high_Quality_Code_Review) { code_Quality.suffers(); } The biggest challenge when it comes to code reviews is time. We all want to provide thoughtful feedback that improves the codebase without spending endless hours dissecting lines of code. – Deliver high-quality feedback. – Do it efficiently. – Minimize the back-and-forth between the author and reviewer. Here’s how to do it: 1. Start with the Change Description Always start with the PR (Pull Request) Description: ↳Understand the Goal: What problem is this change solving? Why is it necessary now? Does it align with the product or technical vision? ↳ Key Design Insights: Look for architectural decisions and trade-offs. Is the proposed solution justified, or are there better alternatives? ↳ Clarity Check: If the PR description needs to be more specific or complete, request the author to refine it. It’s better to clarify the intent than to misunderstand the implementation. 2. Focus on the Interface First Now, move on to the interface, not the implementation. ↳Abstraction: Does the interface present a clean abstraction? Is it intuitive for others to use? A good abstraction hides unnecessary details and provides a natural way for other parts of the system to interact with the component. ↳ Naming Conventions: Are the names of methods, classes, or variables clear and self-explanatory? Names should reflect their purpose without needing additional comments. ↳Contracts: -Does the interface define clear inputs, outputs, and side effects? - Inputs and Preconditions: What does the function or class expect? - Outputs and Postconditions: What does it guarantee? - Side Effects: Are there implicit changes, such as modifying global state? 3. Review the Implementation and Tests Last Once the interface is solid, dive into the implementation. Here’s how to structure your review: ↳ Correctness: –Does the implementation meet the intended functionality? –Test it against the stated goals in the PR description. ↳Edge Cases: Does the code handle unexpected inputs gracefully? –What happens if something goes wrong (e.g., network issues, null inputs)? – Can someone unfamiliar with the change understand the logic quickly? –Use proper indentation, modularization, and logical flow. –Is the solution simpler than necessary? ↳Efficiency: Does the code perform well under expected load? - Are there any unnecessary loops or expensive operations? - Is memory or CPU usage optimized? ↳ Test Coverage Checklist - Do the tests cover all important scenarios, including edge cases? - Tests should be simple and obvious. Avoid abstracting tests too much, even if it involves repetition. - If this change fixes a bug, ensure there’s a regression test to prevent it from resurfacing. - For changes with performance implications, validate them under real-world conditions.

If you ask an engineer to review a small chunk of code, like 20 lines, they’ll spot several issues. But hand them a larger piece, like 500 lines, and they might just skim through it. When you see a pull request that's too big, ask to break it into smaller, manageable parts. When you break your code reviews into smaller parts: 1. You get a well-done plan of execution of your changes 2. ⁠It’s easier to catch bugs and optimize the reviewer’s time 3. ⁠It takes less time in the overall process 4. It’s easier to test and add coverage As opposed to pushing 10s of changes for code reviews, there you are: - not optimizing reviewer’s time to issue code comments  - adding more time to the overall process - making it easy to lose sight of bugs