How to conduct a code review

Code reviews (and upstream architecture and design reviews) are a crucial stage in the software development process. Analysis by one or more other developers helps to improve the quality of the work, while promoting knowledge sharing within the team.

However, it is not uncommon to find that code reviews are often too limited. The focus is mainly on checking the syntax and, if necessary, the coding style.

In Python, these issues are largely covered by automatic tools such as Black or Ruff (and integrated into our suite of command-line development tools, Abilian Dev Tools).

But it is important to remember that the purpose of a code review goes much further. It involves broader reflection and the formulation of questions that the original developer might have overlooked, being too focused on getting the job done.

Here is a list of exploratory questions that we use during code reviews. They are divided into 4 phases, from design to deployment:

Development / design

• What is the origin of this task? What problem is it trying to solve?
  • What impact does this task have on end users? Has it been designed with their needs in mind?
  • What are the business or organisational objectives behind the task? Are they clearly defined and aligned with the proposed implementation?
• Is the scope of the task clearly defined and understandable?
  • How has the task been broken down into smaller, manageable sub-tasks? Is this division logical and efficient?
• How is the system expected to behave in different scenarios?
• Have any extreme cases been omitted or poorly handled?
• Has the user interface been adequately taken into account?
• How does this task fit into the overall system architecture? Does it respect existing design principles and models?
• What impact does this task have on the other systems or services with which it interacts?
• What other solutions have been considered to solve this problem and why has this specific solution been chosen?
• How can this functionality evolve in the future? Is it flexible enough to accommodate future changes?
• Have performance considerations been taken into account from the outset of the design?
• Do any regulatory compliance requirements or constraints (e.g. RGPD, HIPAA, etc.) affect the design?
• Does the design take into account accessibility for all users, including those with disabilities or using assistive technologies?

Construction

• Do you have a precise and complete understanding of what has been built?
• What is the user experience like? Is it intuitive and accessible?
• Is the code consistent with the team's coding conventions and standards?
• Does the code make effective use of available libraries and frameworks?
• Is the code sufficiently documented to enable other developers to understand how it works?
• Is the code structured in such a way as to minimise complexity and maximise readability?
• Has the functionality been developed using test-driven development (TDD) principles?
• What is the coverage of unit, integration and functional tests?
• Have existing tests been adapted or have new tests been added to take account of changes?
• Does the code contain duplications that could be avoided by refactoring or extraction into common functions/methods?
• Have potential optimisation problems been addressed? How does the code perform in terms of performance? How does the system manage scalability?
• How does the code handle errors or unexpected situations? Is this done in an appropriate and transparent way for the user?
• Is the code designed to be scalable? Does it allow for future modifications or extensions without adding too much complexity?
• Has local development been affected in any way?
• Have security issues been addressed and resolved?

Verification

• Are you satisfied that the system works as intended?
• Is there a quality assurance strategy?
• Have any scenarios been left untested?
• What other parts of the system should be regression tested?
• Have static code analysis or security analysis tools been used to check the code?
• (If yes) Have potential problems reported by static code analysis tools been resolved?

Deployment/production release

• Do you have a plan for launching this functionality? Is this plan feasible and secure?
• Has deployment been planned to minimise service interruptions?
• Is there a risk of data loss? If so, have preventive measures been taken?
• How will the system behave during deployment?
• How will the deployment be monitored and what are the success criteria?
• What contingency measures have been planned in the event of deployment failure? Is there a clear downgrade plan?
• How will users be informed of the roll-out and any service interruptions?
• How will post-deployment issues be handled and by whom?
• What monitoring measures are in place to track the behaviour of the new functionality in production?
• Have load or stress tests been planned to ensure that the new functionality can handle production demand?
• Does deployment require updates to user documentation or training for end users?
• How will user feedback and bug reports be collected and processed after deployment?
• How will subsequent updates or enhancements to this functionality be managed?

By asking ourselves these questions during code reviews, we can deepen our understanding of the work done and anticipate potential problems. These questions help us to focus not only on the 'what' (what the code does), but also on the 'why' (why it was written the way it was) and the 'how' (how it could be improved). This leads to a deeper understanding and better collaboration within the team.

More generally, the benefits of code reviews conducted using this methodology are as follows:

1. Improved code quality : Code reviews enable bugs, logic errors or deviations from business requirements to be detected and corrected before the code is deployed in production. This helps to reduce debugging and subsequent maintenance costs.

2. Knowledge sharing : Code reviews encourage knowledge sharing within the team. Developers learn new techniques and approaches by examining the work of their peers. In addition, it ensures that several team members understand each part of the code, which reduces the risk associated with dependence on a single person (the "bus factor").

3. Consistency: Code reviews help to maintain the consistency of the code base by ensuring that all developers adhere to the same coding standards and conventions.

4. Learning and professional development: Code reviews are an excellent opportunity for developers, whatever their level of experience, to receive feedback on their work and improve. They can help new developers understand the code base and assimilate best practice more quickly.

5. Collaboration: Code reviews encourage collaboration and communication within the team. They require regular interaction and open up lines of communication that might not otherwise exist.

6. Risk reduction: Code reviews help to minimise risks in terms of security, performance or compatibility. They can also help to identify upstream architecture or design problems that could be difficult and costly to resolve at a later date.