Code Review Guidelines
Code reviews are a necessary and important step of the software development lifecycle and having a solid process can improve both the quality and speed of delivery. It also has the added benefit of sharing what we work on with our teammates.
Here are some general guidelines to help make your team’s code reviews better. These guidelines can be applied to a wide range of source code — from application development to infrastructure. Let this be a starting place to build good habits on code reviews.
General Guidelines
- Peer reviews should be thoughtful and compassionate.
- Comments should be constructive, not critical.
- Include code samples and links if possible.
- Merged code reflects the whole team not just the individual.
- High level decision making should be done in project planning, not in code review.
- Find good things to say!
Where to start
Questions to consider when reviewing code and tickets:
- Does the solution presented solve the problem in the best way possible?
- Does the solution follow coding standards and best practices established by the team?
- Is the code readable and maintainable?
- If there is opportunity for documentation, was it included (ADR’s, Runbook, README, etc.)?
- Is there adequate test coverage?
Types of comments
Sometimes we want to make a light suggestion, or ask a clarifying question, but not block the pull request from being merged. We can tag our comments as such with — [comment], [question], [blocker], and [recommended]. You can use Github saved replies to make it easier.
Here are some examples of each:
- [blocker]: we shouldn’t merge the code until this is resolved. potential to cause an issue in production, misalignment with team’s established coding standards, code doesn’t function as intended
- [question]: A question to provide clarity or explanation. “Why is the default set to 2?”
- [recommended]: Offer a clear and precise recommendation. “We can improve performance by changing this line of code to be… [code snippet]”. “As a suggestion, the variable name
descriptive_variable_namecould read better here." - [comment]: “Nice work!”, variable/class/object name isn’t clear, formatting, code isn’t readable
Receiving reviews
Responding to code reviews takes just as much careful consideration as reviewing. Take the time to consider all comments and feedback, not just blockers.
Useful reads that helped build this post
Five tips for more helpful code reviews
