As a company we value code review as a way of ensuring quality in our the code bases we work on. But what makes a good code review? Here are some thoughts.
Understand what the new code is supposed to do.
Developers spend the majority of their time reading code, not writing it.
Thus, it is important to make sure the code committed to a codebase is readable. If you cannot understand it when you review it, it will also be hard for you to understand it when you are debugging it in the future.
Here are a few items you might want to think about:
- Can you understand what is happening by reading the code?
- Do the function names make sense?
- Do the variable names make sense?
- Are there long functions doing multiple tasks that should be broken up into smaller tasks?
Even without reading the code, there should be clues to the objective of this code. Look for those in the Pull Request description and the link to the work task, chore or story the code is written to address.
After looking through those to get oriented, read through the code. If you still don’t understand what it is doing, ask questions.
Look for tests to help you understand the code.
We do not typically add comments to the code we write. Rather, we rely on well-named variables and methods and tests to document code.
Tests should demonstrate that the code works, and descriptive naming in tests should outline the context and scenarios the code is meant to work in.
Do not make style-based comments.
If you are commenting on missed semicolons or optional parentheses, your code base needs an automated linting strategy. If a machine can do it, why are you doing it?
After running through this list with the code you are reviewing, you should find something to comment on. Even if your only comment is a question to learn more about how the code works, the review process has achieved its goal – multiple people understand the codebase and have verified the new code makes sense and does what it says it does.