It’s always a challenge to efficiently evaluate code in Pull Requests (PRs) while managing a growing workload. Senior software engineers need a concise, actionable code review checklist for thorough yet swift PR reviews, which are vital for maintaining high-quality codebases.
But the question is what to look for in a code review?
Effective code reviews require balancing technical accuracy with constructive feedback, encouraging team growth. The code reviewer should focus on identifying bugs and design issues, while also sharing insights and best practices, thus creating a collaborative learning environment.
This guide offers a code review checklist with best practices tailored for senior engineers reviewing PRs, ensuring comprehensive coverage. It highlights the key aspects of great reviews, aiming to improve code quality and project success, and equipping engineers for effective code review practices.
Code Review Checklist
Here is an essential 24-point code review checklist, strategically categorized to guide you on what to look for in a code review:
Code Quality
1. Clarity and Readability
Start by assessing the purpose and functionality of the code. Ensure variable, function, and class names are self-explanatory and logically grouped. Check for simplicity and avoid complex structures. Consistent coding style, including naming, indentation, and spacing, is essential for maintainability.
Names should be descriptive, clear, and adhere to language-specific standards. Avoid generic names like “data” and ensure names accurately reflect their purpose. Follow language-specific conventions, like PascalCase in Java and snake_case in Python, and avoid misleading names that could cause confusion or bugs.
Example: In Java, a class handling customer orders is named OrderProcessor instead of a vague Processor or misleading OrderViewer.
2. DRY Principle
Look for repeated code that could be refactored (Don’t Repeat Yourself). Repeated blocks can be replaced with functions or components. Be cautious not to over-engineer, aiming for a balance between reusability and simplicity.
Example: If multiple functions in a codebase format dates, replace them with a single formatDate() function.
3. SOLID Principles
Ensure adherence to SOLID principles in object-oriented design. Each class or module should have a single responsibility, be open for extension but closed for modification, allow derived classes to substitute base classes, not force unnecessary methods on implementing classes, and depend on abstractions rather than concretions.
Example: A FileReader class should only handle reading files, not parsing file data, adhering to the Single Responsibility Principle.
4. Error Handling
Robust and consistent error handling is crucial. Ensure comprehensive coverage of potential errors, including technical and business logic errors. Apply a consistent strategy across the codebase, whether using exceptions or error codes, and ensure errors are handled gracefully without exposing sensitive information.
Example: In a web application, database connection failures throw a custom DatabaseConnectionException, which is caught and logged, and a user-friendly error message is displayed.
Code Performance
5. Efficiency
Assess the algorithms and data structures for their time and space efficiency. Analyze their complexity and consider more efficient alternatives for large data sets. Profile to identify performance hotspots and focus on optimizing these areas. However, avoid premature optimization that complicates code unnecessarily and ensure justifications with performance metrics.
Example: Replacing a nested loop in a data processing script with a more efficient hash table-based approach, significantly reducing time complexity.
6. Resource Management
Ensure efficient management of resources like memory and file handles. Check proper allocation and deallocation to avoid memory leaks. Utilize language features like C#’s “using” or Java’s “try-with-resources” for resource management. Ensure cleanup occurs even when exceptions are thrown, using constructs like “finally” blocks.
Example: In a Java application, using “try-with-resources” to automatically close file streams, ensuring no file handle leaks occur, even if an IOException is thrown.
7. Scalability
Evaluate the code’s ability to handle increased loads. Check for potential bottlenecks and assess if the architecture supports horizontal or vertical scaling. Future-proof the code by ensuring it is modular and can adapt to growth, allowing different system parts to scale independently.
Example: Designing a web service with microservices architecture, allowing individual components to scale independently as user load increases.
8. Concurrency
Review the handling of multi-threading and synchronization. Ensure correct concurrent execution and address issues like race conditions and deadlocks. Check if the use of concurrency is justified and efficient. Concurrent code must be rigorously tested, including load testing under concurrent conditions, to ensure stability and correct behavior.
Example: Implementing thread-safe operations in a multi-threaded application, using locks to prevent race conditions when accessing shared resources.
Security
9. Input Validation
Validate all inputs for type, length, format, and range. Ensure user inputs and data from other systems are checked defensively. Consider sanitization for inputs used in SQL or HTML to prevent malicious content. Provide clear feedback for invalid inputs, guiding users to correct errors without revealing system details.
Example: In a web form, validate email addresses for correct format and length, and sanitize inputs to prevent SQL injection.
10. Authentication and Authorization Checks
Ensure standard protocols and libraries are used for authentication and authorization. Review coverage of protected resources, ensuring all access points are secure. Apply the principle of least privilege, granting users and services minimal access necessary for their function.
Example: Implementing OAuth for user authentication in an application and using role-based access control to restrict user actions based on their roles.
11. Secure Coding Practices
Stay informed about common vulnerabilities like SQL injection and XSS. Implement preventive measures, such as using prepared statements for SQL and sanitizing user inputs. Use security auditing tools to detect vulnerabilities and stay updated with security best practices.
Example: Using prepared statements in database queries to prevent SQL injection and implementing content security policies to mitigate XSS risks.
12. Data Encryption
Ensure sensitive data is encrypted in transit and at rest using up-to-date, standard encryption methods. Verify secure key management and comply with relevant regulatory requirements like GDPR or HIPAA.
Example: Encrypting user passwords with a robust hashing algorithm like bcrypt and using HTTPS to secure data in transit.
Testing and Reliability
13. Unit Tests
Comprehensive unit tests should cover critical paths, be well-structured, and easy to maintain. They need to cover common, edge, and error scenarios, and be independent of external systems. Mocking is essential for isolating the code under test.
Example: In a Java application, using JUnit and Mockito for testing a method that calculates the sum of a list of numbers. Mocking is used to provide a controlled list of numbers.
import static org.junit.Assert.*;
import org.junit.Test;
import org.mockito.Mockito;
import java.util.Arrays;
import java.util.List;
public class CalculatorTest {
@Test
public void testSum() {
Calculator calculator = new Calculator();
List<Integer> numbers = Arrays.asList(1, 2, 3);
int result = calculator.sum(numbers);
assertEquals(6, result);
}
}
14. Integration Tests
Integration tests should ensure different system parts work together effectively, covering real-world scenarios and failure modes. The test environment must mimic production.
Example: Using Python’s pytest for testing an API endpoint in a Flask application. The test ensures that the endpoint returns the correct status code and data format.
import pytest
from flask import Flask
from myapp import create_app
@pytest.fixture
def app():
app = create_app()
return app
def test_get_endpoint(client):
response = client.get("/api/data")
assert response.status_code == 200
assert isinstance(response.json, dict)
15. Test Coverage
Evaluate test coverage for critical code paths using coverage analysis tools. Aim for a balance between high coverage and test quality.
Example: Using a coverage tool like Istanbul in a Node.js application to measure test coverage. Running the coverage report highlights untested parts of the application.
npx istanbul cover _mocha tests/*.js
16. Code Consistency
Maintain consistency in coding practices across the codebase, including naming, structures, and patterns. Document coding conventions and regularly update them.
Example: Refactoring a JavaScript codebase to use ES6 arrow functions consistently for anonymous functions, as part of aligning with updated coding standards.
// Before
[1, 2, 3].map(function (x) { return x * x; });
// After Refactoring
[1, 2, 3].map(x => x * x);
Documentation and Comments
17. Code Comments
Verify that comments explain complex logic and decisions, avoiding redundancy with the code. Ensure comments are up-to-date, reflecting recent code changes, and adhere to the project’s style.
Example: In a Python function, comments explain the use of a specific algorithm due to its efficiency in handling large datasets.
# Using QuickSort as it provides O(n log n) performance on large datasets
def quick_sort(sequence):
# Implementation details
18. Technical Documentation
Review documentation for accuracy, completeness, and clarity. It should reflect the code’s current state, covering system structure and interactions, and be accessible to newcomers.
Example: A software design document outlines the architecture, data flow, and external dependencies of a microservices-based application.
19. README/Changelogs
Ensure the README is informative and current, and changelogs chronologically list significant changes. Both should be clear and well-formatted for ease of reading.
Example: A project README includes setup instructions, usage examples, and links to further documentation, while the changelog details version-specific updates.
Compliance and Standards
20. Code Standards
Confirm adherence to coding standards and suggest automated linting tools for enforcement. Document these standards for team alignment.
Example: A JavaScript project uses ESLint for linting, ensuring consistent coding practices like indentation, variable naming, and arrow function usage.
21. Legal Compliance
Check for compliance with licenses, data protection laws, and intellectual property rights. Ensure proper handling of user data and authorization for code use.
Example: A software license audit confirms compliance with open-source licenses, and privacy policies align with GDPR for user data management.
22. Accessibility
Review for compliance with accessibility best practices and suggest tools for testing. Documentation should cover accessibility features.
Example: A web application is tested for screen reader compatibility and keyboard navigation, with ARIA roles implemented for UI components.
Design and Architecture
23. Design Patterns
Evaluate the appropriate and consistent use of design patterns, ensuring they address specific problems effectively. Documentation should explain their rationale.
Example: In a Java application, the Singleton pattern is used for a database connection manager, ensuring a single instance throughout the application.
24. Architecture Decisions
Assess code alignment with architectural principles, considering scalability, performance, flexibility, and maintainability. Identify potential bottlenecks in the architecture.
Example: In a cloud-based service, review the code for alignment with microservices architecture, assessing the efficiency of inter-service communication and database interactions.
Conclusion
A senior software engineer’s code review must prioritize clarity, efficiency, and security, ensuring code is readable, performant, and secure. Adherence to established conventions, like naming and SOLID principles, alongside robust error handling, forms the foundation of high-quality code. It’s imperative to routinely evaluate these aspects to maintain and enhance codebase integrity.
Furthermore, a comprehensive review extends beyond code quality to encompass testing, documentation, compliance, and design. Effective unit and integration tests, accurate documentation, adherence to coding standards, and alignment with architectural principles are crucial. This holistic approach guarantees not only the current functionality but also the future adaptability and sustainability of the codebase.
Top comments (2)
Hey, you have
17. Code CommentstwiceBut also I would focus on comments that explain WHY not WHAT
Those comments can be why more useful for readers
Nice read. Thanks for sharing!
Some comments have been hidden by the post's author - find out more