Live streamJoin us for "State of code review 2024" on July 18thRegister today

Best practices for code reviewers

Greg Foster
Greg Foster
Graphite software engineer

A successful code review process is a delicate balance between rigorous examination and a collaborative, non-threatening environment. The following best practices for code reviewers ensure that the process is both effective and conducive to team growth.

A successful code review process is a delicate balance between rigorous examination and a collaborative, non-threatening environment. The following best practices for code reviewers ensure that the process is both effective and conducive to team growth.

Effective commenting during code reviews bridges the gap between identifying an issue and providing a pathway to improvement. Clear, constructive feedback not only enhances code quality but also fosters a supportive environment where developers are encouraged to learn and refine their skills.

  • Constructive Comments: Feedback should be constructive, focusing on the code and not the coder. Avoid overly critical or personal remarks.

  • Actionable Suggestions: Comments should provide clear, actionable suggestions for improvement. For example, instead of saying "This is wrong," suggest "Consider refactoring this method to improve readability."

  • Use of Checklists: Employ checklists to ensure all essential review points are covered. Checklists can prevent common oversights and help maintain a consistent review process.

  • Annotation Use: Encourage authors to annotate their code submissions, clarifying changes and reasoning, thus facilitating a deeper understanding during the review.

Good Commenting Strategy Example: Comment: "The calculateInterest method might not handle negative inputs correctly. Adding input validation could prevent potential issues with range."

Bad Commenting Strategy Example: Comment: "This method doesn't handle negatives—seems like an oversight."

Identifying code smells—a term for symptoms in the code that may indicate deeper problems—is vital for maintaining a healthy codebase. Recognizing these patterns early prevents technical debt, facilitates easier maintenance, and ensures scalability.

  • Limit Review Size: Review no more than 400 lines at a time to maximize defect detection, as recommended by the SmartBear study​​.

  • Frequent Short Reviews: Shorter, more frequent reviews are more effective and less taxing on the reviewers, preventing fatigue and oversight.

  • Omission Checking: Use checklists to look for omissions, which are the hardest defects to detect because it’s difficult to review something that isn't there​​.

Good Code Smell Identification Example: Observation: "The method processTransaction has a high cyclomatic complexity, indicating it could be refactored for simplicity and clarity."

Bad Code Smell Identification Example: Missed Opportunity: Reviewer fails to comment on the complex method, missing the chance to improve code quality.

Security and performance are not afterthoughts but are integral to the development process. Addressing these considerations during code reviews reinforces the defense against potential vulnerabilities and ensures the application operates efficiently under load.

  • Security Checks: Ensure that new code adheres to security best practices, like checking for proper authentication, authorization, and input validation to prevent common vulnerabilities.

  • Performance Metrics: Reviewers should be mindful of the performance implications of code changes, looking for potential inefficiencies or resource-intensive operations.

  • Automated Tools: Utilize automated tools for static code analysis to catch security and performance issues before they reach the human review stage.

Good Security Consideration Example: Feedback: "To protect against SQL injection, we should parameterize this database query."

Bad Security Consideration Example: Oversight: "The application runs without errors. SQL injection isn't a concern right now."

Setting clear goals and measurable metrics for code reviews ensures the process is targeted and beneficial. It transforms code reviews from a mere formality into a strategic tool for continuous improvement and accountability.

A structured defect-fixing process ensures that issues identified during reviews are promptly and effectively addressed. This not only streamlines the development cycle but also reinforces the value of the code review process.

Cultivating a positive code review culture is about more than just improving code; it's about building a team that values growth, collaboration, and mutual respect. This mindset turns code reviews into a collective step toward excellence.

The 'Ego Effect'—the desire to present one's best work to peers—naturally drives developers to produce higher-quality code. Utilizing this effect can lead to more conscientious coding and thorough self-review before peer evaluation.

Implementing lightweight reviews streamlines the code review process, making it less burdensome and more focused. This approach respects the reviewers' time, reduces overhead, and accelerates the development cycle.

By following these practices, reviewers can significantly contribute to the code quality and maintain a positive, productive code review environment.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2