Code review checklist: Why you need one and how to use it effectively

Bad code makes for a maintenance nightmare down the line. Once committed, bad code becomes technical debt, and technical debt becomes overwhelming when you don’t go back and fix it. Developers spend 33% of their time dealing with technical debt. How can you prevent technical debt from accruing? With effective and comprehensive code reviews. And how can you make code reviews achieve their goals? A code review checklist is a good start.

What is a code review?

Code review is a process of vetting code by another programmer. The primary purpose of code review is to maintain high code quality. Reviewing code can expose issues in logic, readability, dependencies and help improve maintainability. Code review is useful in any team and can even be done by a solo developer with the help of a checklist.

The secondary purpose of code review is to enable team members to collaborate and learn from each other. It doesn’t have to be a senior developer reviewing a junior team member for the transfer of knowledge to be fruitful.

Who should do code reviews?

The short answer is everyone. There are different approaches to choosing who will review code, and each method has its pros and cons. Usually, you want some healthy mix of everything, although that is not without risk. What does that mean?

Having senior developers review has the advantage of all code passing through experienced reviewers. The downside is that senior developers’ time is more valuable and expensive, and you may prefer they spend their time doing other things. Junior developers reviewing each others’ code is efficient, but you risk missed issues and lower code quality.

When a developer with specialized knowledge reviews code, they are more likely to catch nuances specific to that area of code. If they are also owners of that codebase, it is beneficial that they are made aware of every change as part of the review process. However, the benefit of a reviewer not being familiar with the changed code is that the developer being reviewed must explain their changes in greater detail thus allowing more team members to familiarize themselves with the code.

What is a code review checklist?

Like any checklist, a code review checklist contains things you should check before committing or merging code. The purpose of a code review checklist is to ensure nothing is forgotten in the code review process. Developers can use a code review checklist to review their solo work. A reviewer can use a checklist to improve their review process of others’ code.

An effective code review checklist will not be too long, as that would make developers reluctant to use it. A self-review checklist might differ from a reviewer’s checklist and emphasize other parts of the code review process. In an organization or a team, you might want to have a standardized code review checklist to maintain a high code standard and cohesiveness throughout your code base.

What should you include in your code review checklist?

Everyone has different needs for code reviews, and the checklist needs to reflect this. You want a checklist that will cover the critical points that most reviewers should cover without becoming bloated. Use the items below to make your checklist, and cross-reference some other checklists you can find online.

Readability and Maintainability

Different developers have varied methods of working on code towards a goal. Most developers I’ve worked with like to jump into the grit of things and start messing around until it works. This method of development can generate unreadable and unmanageable code. Once the code works, you should reevaluate it to see if it meets a good standard. It may be prudent to rewrite the code, or it may only need some formatting, in-line documentation and readability changes.

• Is the code understandable? – Can someone who has never seen it clearly understand what the code does without help? If not, you may want to break the code down into smaller functions or add comments.
• Are packages and namespaces in order? – Something as simple as this can create an unnecessary headache down the road.
• Does the code chance achieve the desired result simply and effectively? – Now that you know how the solution works, can you think of a better one? Simple code is easier to maintain.
• Does the code formatting and styling adhere to your organization’s standards? – Formatting conventions help with readability as code becomes integrated into other code.
• Can variables, method names, or classes be renamed to improve readability? – Sometimes, making names longer can help explain the code without the need for comments.
• Can the code’s readability be improved by breaking up methods into smaller ones? – Big bulky methods are harder to understand. Splitting methods into smaller ones not only helps understand them but giving them meaningful names makes for self-documenting code.
• Should a comment explain why the code was designed the way it was? – Sometimes, self-documenting code isn’t enough, and a comment that gives an overview of the design is needed.

You can put many other items on this list, especially related to comments.

Performance and Databases

While rapid prototyping encourages developers to write quick and dirty code and worry about performance when necessary, some applications rely on performance to deliver a good user experience. If your application requires good performance, make sure you have several items on your checklist to address it.

• Should the new code be profiled for performance?  – If performance is of concern, running the code through a profiler is the first step in learning if changes need to be made.
• Are there any logging or debugging code that should be removed? – Logging in the wrong place can have a significant impact on performance.
• Is caching or lazy loading used where applicable? – Caching and Lazy loading are two common ways to improve performance.
• Is the correct data structure being used to store collections? – Should your collection be a set or a list?
• Is the most efficient data type used for the expected values? – Database types can be fine-tuned to be memory efficient based on the expected values.
• Could a Stored Procedure be used instead of code? – Stored procedures are often a better solution than code, both for maintainability and performance.
• Can performance be improved by indexing? – Sometimes adding an Index can help, sometimes removing one can. Make sure indexing is used correctly.
• Are queries returning unnecessary data that could be trimmed? – Returning too much data is wasteful. Make sure you’re querying for the data you need.

There are possible other concerns that are specific to different types of databases. Add items that are specific to the database you’re using.

Security

Security is a serious concern these days, and shifting left security as early as possible can save resources and reduce risk.

• Are your queries sanitized against SQL injections? – SQL injections are an easy avenue of attack. Make sure to take the necessary precautions.
• Do error messages give too much information to potential attackers? – Sometimes, error messages can hand would-be attackers the keys to the fort. Be informative, but not too informative.
• Is Authentication and Authorization handled correctly? – If the code area doesn’t directly deal with authentication and authorization, it might still need to do security checks.
• Is user input validated? – You don’t want user input to go unchecked.

Different organizations will have additional security standards, and you’ll need to make your checklist compatible with those standards. Other categories you may want to include in your checklists include UX/UI, Error Handling, Unit Testing, Automation, and Compatibility.

How AI can help streamline code review

Code reviews should focus on the big picture. The feedback you’re giving another developer needs to be constructive, and it must be manageable. You don’t want to give a developer a hundred small changes they need to make; you want to provide them with very few overview comments to improve the code. Small mistakes in grammar and naming conventions can inflate the number of comments you’re giving and make it harder for the developer to accept the feedback. AI can reduce the number of low-level mistakes, streamline the majority of the readability and naming issues, and give you a cleaner starting point.