Code Review Best Practices

In the last 11 years of my career, I’ve participated in code reviews almost daily. I’ve sat through 100s of review sessions with seniors and colleagues. Here’s how to make your code reviews smoother, faster and easier: 1. Start with Small, Clear Commits    - Break your changes into logical, manageable chunks. This makes it easier for reviewers to focus and catch errors quickly. 2. Write Detailed PR Descriptions    - Always explain the “why” behind the changes. This provides context and helps reviewers understand your thought process. 3. Self-Review Before Submitting    - Take the time to review your own code before submitting. You'll catch a lot of your own mistakes and improve your review quality. 4. Ask for Specific Feedback    - Don’t just ask for a “review”—be specific. Ask for feedback on logic, structure, or potential edge cases. 5. Don’t Take Feedback Personally    - Code reviews are about improving the code, not critiquing the coder. Be open to constructive criticism and use it to grow. 6. Prioritize Readability Over Cleverness    - Write code that’s easy to understand, even if it’s less “fancy.” Simple, clear code is easier to maintain and review. 7. Focus on the Big Picture    - While reviewing, look at how changes fit into the overall system, not just the lines of code. Think about long-term maintainability. 8. Encourage Dialogue    - Reviews shouldn’t be a one-way street. Engage in discussions and collaborate with reviewers to find the best solution. 9. Be Explicit About Non-Blocking Comments    - Mark minor suggestions as “nitpicks” to avoid confusion. This ensures critical issues get addressed first. 10. Balance Praise and Criticism    - Acknowledge well-written code while offering suggestions for improvement. Positive feedback encourages better work. 11. Always Follow Up    - If you request changes or leave feedback, follow up to make sure the feedback is understood and implemented properly. It shows you’re invested in the process. -- P.S: What would you add from your experience?

I don’t think the main primary purpose of code reviews is to catch bugs. Most dev do. They’ll tell you reviews are about quality control. But I disagree. The most valuable part of a code review is knowledge transfer. Here's why: - Developers usually test their code before opening a PR - Most teams already use linters, static analysis, and CI to catch issues What teams do not do enough of is share why the code was written a certain way and capture architectural decisions so future engineers understand the tradeoffs On a fast moving distributed team it is impossible for everyone to be in every call or track every ticket. Code reviews become the last line of defense for distributing knowledge Here are 4 ways to make code reviews a knowledge sharing superpower: 1. Always explain the “why” behind your code, not just the “what" 2. Document architectural decisions either in the PR itself or by linking to an ADR 3. Summarize the PR in plain English so anyone can quickly understand what changed and why 4. If a decision was made in Slack or a meeting, record it in the PR so it is not lost

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.

9 code review practices your team should follow to go from Good → Great projects. (these helped my team deliver 100s of projects without wasting hours fixing bugs) 🟢As a team: ➡️Establish goals and expectations beforehand: for example: + functional correctness + algorithmic efficiency + improving code quality + ensuring code standards are met ➡️Use code review tools Use: (GitHub PRs, GitLab MRs, and Atlassian Crucible). + easily track changes + streamline the review process ➡️Automate code checks:  It will help you to: + find syntax errors + avoid common issues + reduce code style violations and potential bugs. 🟡As a reviewer: ➡️Start early, review often:  do this to: + catch issues early + prevent technical debt + ensure that code meets project requirements. ➡️Keep reviews small and focused:  you get: + an easier process + shorter turnaround time. + better collaboration in the team ➡️Balance speed and thoroughness:  + do comprehensive reviews  + but avoid excessive nitpicking ➡️Give constructive feedback: always be: + specific, actionable, and respectful + focus on improvement rather than criticizing.  + make a space for open communication to answer questions & give clarifications. 🟠As a reviewee: ➡️follow up on feedback:  + don’t take the comments personally + actively work on feedback after the session + make necessary revisions and follow up to confirm ➡️Follow coding standards:  focus on improving: + readability + maintainability Remember - mutual respect during the code reviews is crucial for a great team culture! – P.S: If you’re a Sr. Software engineer looking to become a Tech Lead or manager. I’m doing a webinar soon. Stay tuned :)